Flashbank
Provides tools for browsing, quoting, and optionally transacting with FlashBank P2P term-loan escrow and flash-loan router contracts on Ethereum and its testnets.
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 |
| create/take/repay/claim/cancel + faucet on Sepolia |
Mainnet writes | …and | 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.
Related MCP server: agentfi-mcp-server
Tools
Read (always available)
Tool | Purpose |
| Plain-English primer on both products — agents should call this first |
| Chains, contract addresses, registry tokens, current write permissions |
| Signer address + native/token balances on a chain |
| Open offers, boosted first, with human-readable terms |
| Full detail: terms, take quote, repayment quote, default split, terms pin |
| Loans created by an address (or the signing wallet) |
| Flash-loan liquidity, fee bps, caps and provider count per token |
| Fee + fundability quote for a flash-borrow amount |
Write (gated as above)
Tool | Purpose |
| Post a lend offer / borrow request (escrows your side; handles the approval; optional |
| Accept an offer, pinning the exact reviewed terms on-chain (terms hash, or version pin on older builds — feature-detected) |
| Repay and redeem collateral; on v2 chains reports the vested fee and any cooling-off rebate |
| Lender claims collateral after the repay window closes |
| Cancel your untaken offer and reclaim escrow |
| v2: withdraw a payout that queued because it couldn't be delivered to you |
| 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 |
| The product primer (same text as |
| Chain/contract/token registry as JSON, incl. per-chain contract versions |
| The v2 fee-vesting model with the exact formula |
| The write-gating model and agent rules of thumb |
Prompt | Workflow |
| Safe first session: faucet → post → inspect → cancel, narrated |
| Compose a sensible lend offer (cushion, fee, term, surplus-return) and place it |
| Shortlist offers, compare true cost + default risk, take with pinned terms |
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-onlyAny other MCP client works the same way — stdio transport, command node src/server.js.
Environment variables
Variable | Default | Meaning |
| unset | Signing key; unset = read-only |
| unset |
|
| public RPC | Override the RPC per chain, e.g. |
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 GlamaThe 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.
Available Tools
15 toolsexplainExplain FlashBankARead-onlyIdempotent
Plain-English primer on both FlashBank products, the loan lifecycle, fees and safety rules. Call this first if you are unsure how anything works.
Inputs: no named parameters.
faucet_mintMint Sepolia play-moneyA
Mint a free batch of 10,000 fpUSD or fpETH (valueless playground tokens) to the signing wallet on Sepolia. The safe way for agents to get funds to experiment with.
Inputs: token (required).
flash_poolsFlash-loan poolsBRead-only
Per-token flash-loan liquidity on a chain: committed amount, live available liquidity, fee, per-loan cap and provider count.
Inputs: chain (required).
flash_quoteQuote a flash loanBRead-only
Fee quote for flash-borrowing a given amount of a token (symbol or address) on a chain.
Inputs: chain (required), token (required), amount (required).
list_chainsList chainsARead-onlyIdempotent
Supported chains with contract addresses, registry tokens and whether writes are currently permitted for each.
Inputs: no named parameters.
p2p_cancelCancel an open P2P offerAIdempotent
Cancel an offer you created that has not been taken, reclaiming your escrow (any boost spend is not refunded). Mainnet gated.
Inputs: id (required), chain (required).
p2p_claim_defaultClaim a defaulted P2P loanADestructiveIdempotent
After the repay window closes unpaid, the lender claims the collateral (any agreed surplus returns to the borrower). Irreversibly settles the loan. Requires the signing wallet to be the lender (mainnet gated).
Inputs: id (required), chain (required).
p2p_create_offerCreate a P2P offerA
Post a loan offer (you lend) or borrow request (you borrow) on-chain. Escrows your side immediately: lenders escrow the principal, borrowers escrow the collateral. Reversible via p2p_cancel while untaken. Requires a signing key; mainnet additionally requires FLASHBANK_MCP_ALLOW_MAINNET=true.
Inputs: side (required), chain (required), flatFee (required), principal (required), +9 more.
p2p_get_loanGet P2P loan detailARead-only
Full detail for one loan id: terms, parties, status, what a taker must provide, repayment quote, default deadline/split and the on-chain terms hash.
Inputs: id (required), chain (required).
p2p_list_offersList open P2P offersARead-only
Open, takeable loan offers/requests on a chain, newest first with boosted (featured) offers ranked on top. Returns human-readable terms plus the raw ids for follow-up calls.
Inputs: chain (required), limit.
p2p_my_loansMy P2P loansBRead-only
Every loan created by or assigned to an address (defaults to the configured wallet), with current status.
Inputs: chain (required), address.
p2p_repayRepay a P2P loanADestructiveIdempotent
Repay an active loan you borrowed, redeeming your collateral. On v2 chains (Sepolia) the fee is the VESTED amount — repaying inside the cooling-off window is rebated down to a 10% floor. Requires the signing wallet to be the borrower (mainnet gated).
Inputs: id (required), chain (required).
p2p_take_offerTake a P2P offerADestructiveIdempotent
Accept an open offer, pinning the EXACT terms currently on-chain (takeWithTerms) so a last-second re-price reverts instead of surprising you. Approves and escrows your side, which activates the loan — a BINDING commitment until repaid or defaulted. Requires a signing key (mainnet gated).
Inputs: id (required), chain (required).
p2p_withdraw_unclaimedWithdraw queued payouts (v2)AIdempotent
v2 chains (Sepolia) only: if a settlement payout to you could not be delivered (e.g. a blocklisting token), it queues on-chain — this checks your queued balance for a token and withdraws it.
Inputs: chain (required), token (required).
wallet_statusWallet statusARead-only
Address, native balance and registry-token balances of the configured signing wallet on one chain. Reports read-only mode when no key is set.
Inputs: chain (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Each tool has a distinct purpose: explain, faucet, flash loans, P2P lifecycle actions, wallet status. No two tools appear to do the same thing; even similar P2P tools are clearly separated by action (create, take, cancel, repay, claim).
Most tools follow a verb_noun pattern (e.g., list_chains, p2p_create_offer, p2p_repay), but a few start with a noun (faucet_mint, flash_pools, wallet_status) and one uses an adjective (p2p_my_loans). Minor inconsistency but still predictable.
15 tools is appropriate for the domain covering flash loan overview, test tokens, chain info, and full P2P lending lifecycle. Each tool serves a needed function without being excessive.
The tool set covers explanation, test funding, flash loan info, P2P offers, actions, and wallet status. A minor gap is the inability to modify an offer (only cancel), but core workflows are complete.
Maintenance
Related MCP Connectors
Non-custodial RFQ and atomic swap settlement for AI agents. Escrow onchain, signed receipts.
Complete financial infrastructure for AI agents — payments, lending, escrow & more.
Non-custodial DeFi for AI agents: swaps, concentrated liquidity (V3/V4) zaps + ranges, 5 EVM chains
Underwritten DeFi yield discovery & goal planning for AI agents on Base & EVM.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to interact with HyperLend protocol and Kittenswap DEX on Hyperliquid EVM network. Supports DeFi operations including lending, borrowing, withdrawing assets, and token swapping with comprehensive portfolio management.8MIT
- AlicenseAqualityBmaintenanceDeFi execution and agent-to-agent economy tools for AI agents — swaps, yield, transfers, policy enforcement, trust scoring, A2A jobs, and P\&L across Ethereum, Base, Arbitrum, and Polygon.311Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with peer-to-peer networks (libp2p) and DeFi protocols, including oracle networks, cross-chain communication, and intent-based execution.2MIT
- AlicenseNot gradedqualityDmaintenanceBroker-only credit/lending discovery shim for AI agents, surfacing real lending markets from licensed/established third-party protocols and routing applications.MIT