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

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.

Related MCP server: Base MCP Server

Tools

Read (always available)

Write (gated as above)

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

Installation

Via npm (recommended — published as @flashbank/mcp):

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

Add "env": { "FLASHBANK_MCP_PRIVATE_KEY": "0x<throwaway-key>" } to enable writes. Claude Desktop uses the same JSON shape in claude_desktop_config.json; Claude Code: claude mcp add flashbank -- npx -y @flashbank/mcp. The server is also listed in the official MCP Registry as io.github.Rotwang9000/flashbank, so registry-aware clients can discover and install it by name.

From this repo:

{
	"mcpServers": {
		"flashbank": {
			"command": "node",
			"args": ["mcp/src/server.js"]
		}
	}
}

The repo ships a project-level .cursor/mcp.json that registers it for Cursor in read-only mode (no env block = read-only).

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

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.