Skip to main content
Glama

FlashBank MCP server

npm MCP Registry Listed on Glama

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.

Related MCP server: agentfi-mcp-server

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

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

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.

Available Tools

15 tools
explainExplain FlashBankA
Read-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 poolsB
Read-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 loanB
Read-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 chainsA
Read-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 offerA
Idempotent

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 loanA
DestructiveIdempotent

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 detailA
Read-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 offersA
Read-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 loansB
Read-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 loanA
DestructiveIdempotent

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 offerA
DestructiveIdempotent

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)A
Idempotent

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 statusA
Read-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

    A3.9/5.0

    Scored across 15 tools

    Disambiguation5/5

    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).

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers