@flashbank/mcp

FlashBank MCP server

A Model Context Protocol server that lets AI agents browse, quote and (optionally) transact with the FlashBank contracts — the P2P term-loan escrow and the flash-loan router — on Ethereum, Base, Arbitrum and the Sepolia playground.

Self-contained: inline minimal ABIs, public RPCs, no Hardhat compilation needed. Read tools work with zero configuration; write tools are opt-in and safety-gated. Beyond the 15 tools it serves resources (flashbank://guide, flashbank://chains, flashbank://cooling-off, flashbank://safety), guided prompts (play_on_sepolia, lend_assets, borrow_against_collateral) and connect-time instructions, and every tool carries MCP safety annotations (readOnlyHint / destructiveHint / idempotentHint) so agent clients can reason about risk before calling anything.

cd mcp && npm install && npm test     # 16 tests incl. a full MCP stdio handshake — no network/key needed
npm run smoke                         # live read-only check against the deployed contracts
npm run drill                         # LIVE two-agent lifecycle drill on Sepolia (needs a funded key)

The drill spawns two real MCP server instances (lender agent + a throwaway borrower agent) and walks faucet → create → browse → take (pinned) → early repay (cooling-off rebate verified) → withdraw-unclaimed probe → cancel, with real transactions on the Sepolia playground.

Safety model

Mode	Requirement	What it allows
Read-only (default)	nothing	browse offers, quotes, pool stats, wallet lookups
Playground writes	FLASHBANK_MCP_PRIVATE_KEY	create/take/repay/claim/cancel + faucet on Sepolia
Mainnet writes	…and FLASHBANK_MCP_ALLOW_MAINNET=true	the same on Ethereum/Base — real assets, real risk

Use a dedicated throwaway key for agents; never a key holding meaningful funds. Mainnet writes are deliberately double-gated and the contracts carry no external audit.

Tools

Read (always available)

Tool	Purpose
explain	Plain-English primer on both products — agents should call this first
list_chains	Chains, contract addresses, registry tokens, current write permissions
wallet_status	Signer address + native/token balances on a chain
p2p_list_offers	Open offers, boosted first, with human-readable terms
p2p_get_loan	Full detail: terms, take quote, repayment quote, default split, terms pin
p2p_my_loans	Loans created by an address (or the signing wallet)
flash_pools	Flash-loan liquidity, fee bps, caps and provider count per token
flash_quote	Fee + fundability quote for a flash-borrow amount

Write (gated as above)

Tool	Purpose
p2p_create_offer	Post a lend offer / borrow request (escrows your side; handles the approval; optional coolingOffHours on v2 chains)
p2p_take_offer	Accept an offer, pinning the exact reviewed terms on-chain (terms hash, or version pin on older builds — feature-detected)
p2p_repay	Repay and redeem collateral; on v2 chains reports the vested fee and any cooling-off rebate
p2p_claim_default	Lender claims collateral after the repay window closes
p2p_cancel	Cancel your untaken offer and reclaim escrow
p2p_withdraw_unclaimed	v2: withdraw a payout that queued because it couldn't be delivered to you
faucet_mint	Mint 10,000 fpUSD/fpETH play-money (Sepolia only)

Flash loans are quote/read only by design: executing one requires a smart contract implementing the borrower callback, which is not something an MCP tool should improvise.

Resources & prompts

Resource	Content
flashbank://guide	The product primer (same text as explain)
flashbank://chains	Chain/contract/token registry as JSON, incl. per-chain contract versions
flashbank://cooling-off	The v2 fee-vesting model with the exact formula
flashbank://safety	The write-gating model and agent rules of thumb

Prompt	Workflow
play_on_sepolia	Safe first session: faucet → post → inspect → cancel, narrated
lend_assets	Compose a sensible lend offer (cushion, fee, term, surplus-return) and place it
borrow_against_collateral	Shortlist offers, compare true cost + default risk, take with pinned terms

Installation

From this repo (works today):

{
	"mcpServers": {
		"flashbank": {
			"command": "node",
			"args": ["mcp/src/server.js"],
			"env": {
				"FLASHBANK_MCP_PRIVATE_KEY": "0x<throwaway-key-funded-on-sepolia>"
			}
		}
	}
}

The repo ships a project-level .cursor/mcp.json that registers it for Cursor in read-only mode (omit the env block and it stays read-only). Claude Desktop uses the same JSON shape in claude_desktop_config.json; Claude Code: claude mcp add flashbank -- node mcp/src/server.js.

Via npm (once published as flashbank-mcp):

{
	"mcpServers": {
		"flashbank": {
			"command": "npx",
			"args": ["-y", "flashbank-mcp"]
		}
	}
}

Via Docker:

cd mcp && docker build -t flashbank-mcp .
docker run -i --rm flashbank-mcp                # read-only

Any other MCP client works the same way — stdio transport, command node src/server.js.

Environment variables

Variable	Default	Meaning
FLASHBANK_MCP_PRIVATE_KEY	unset	Signing key; unset = read-only
FLASHBANK_MCP_ALLOW_MAINNET	unset	true unlocks mainnet writes
FLASHBANK_MCP_RPC_<CHAIN>	public RPC	Override the RPC per chain, e.g. FLASHBANK_MCP_RPC_ETHEREUM

Layout

src/chains.js         chain registry (addresses, tokens, RPCs, p2pVersion) — update on redeploys
src/abi.js            inline minimal ABIs, version-aware (v1 mainnets, v2 Sepolia playground)
src/clients.js        providers, signer, write gate, token resolution, allowances
src/format.js         pure formatting helpers (unit-tested)
src/server.js         the MCP server: tools, resources, prompts, annotations
scripts/mcp-client.js minimal stdio client shared by the protocol test and the drill
scripts/smoke.js      live read-only smoke against the real deployments
scripts/drill.js      live two-agent lifecycle drill on Sepolia
test/                 node:test suites incl. a full MCP stdio protocol test
Dockerfile            container build (stdio entrypoint), used by hosts like Glama

The listing on Glama is maintained via the repo-root glama.json.

The Sepolia playground runs FlashBankP2PLoanV2 (0x536f…1E76): cooling-off rebate, token validation and pull-payouts (see docs/design/P2P_V2_COOLING_OFF.md). Mainnets stay on v1 until v2 graduates.