flare-mcp — Model Context Protocol Server for Flare Network

The first Model Context Protocol server for Flare Network — query FTSO price feeds, FAssets, FDC attestations and proofs, balances and Smart Accounts in natural language from Claude Desktop, Cursor, VS Code or any MCP-compatible client. Runs locally over stdio as an npx package: no server to host, no cost.

v2 adds FDC attestation workflows (request + locally-verified proofs), deep FAssets state (per-agent collateral and liquidation status, system totals, redemption queue), Songbird/Coston support, and an FCC (Flare Confidential Compute) registry watcher. All reads are trustless where possible: FDC proofs are Merkle-verified locally against the on-chain Relay root, never trusted from an API. The only optional write is fdc_request_attestation, which submits an attestation request if you configure FLARE_PRIVATE_KEY — without it the tool returns a prepared request for your own signer, and the server never holds or forwards funds.

Features

• get_flr_balance — Native FLR and wrapped WFLR (WNat) balance for any EVM address.

• get_ftso_feed — Latest FTSO v2 price for a single feed, by name (FLR/USD) or raw bytes21 id.

• get_ftso_feeds_all — Latest FTSO v2 prices for all bundled feeds in one call.

• get_ftso_providers — Active FTSO data providers (vote power, fee, reward rate). Needs an indexer endpoint — see Environment Variables.

• get_ftso_history — Recent historical FTSO results for a feed. Needs a Data Availability Layer endpoint — see Environment Variables.

• get_fassets_status — FAssets status (total minted, active agents) for FXRP, FBTC or FDOGE, read on-chain.

• get_fdc_proof_status — FDC (protocol id 200) Merkle root and finalization status for a voting round.

• get_smart_account_info — Resolve the deterministic Flare address for an XRPL (r...) account via the MasterAccountController.

New in v2:

• fdc_request_attestation — Submit an FDC attestation request (Payment, AddressValidity, EVMTransaction): prepares it via a Flare-hosted verifier, quotes the request fee, and submits to FdcHub (or returns the prepared request if no key is configured).

• fdc_get_attestation_proof — Fetch an attestation proof from the Data Availability layer and verify the Merkle proof locally against the Relay root read on-chain.

• fassets_agent_status — Every FAssets agent with collateral ratios, minting capacity, minted/reserved amounts and liquidation status, sorted riskiest-first.

• fassets_system_state — Global FAssets stats: total minted, lot size, minting cap/pause, aggregated vault+pool collateral, redemption queue.

• songbird_fcc_registry — Live FlareContractRegistry scan for Flare Confidential Compute (PMW/TEE) deployments post-STP.13.

It also exposes two MCP resources: flare://network/feeds (the bundled FTSO feed list) and flare://network/contracts (the ContractRegistry address and runtime-resolution guide).

Related MCP server: Hermes Blockchain Oracle

Quick Start — Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) and add:

{
  "mcpServers": {
    "flare-mcp": {
      "command": "npx",
      "args": ["-y", "@dziuba0x/flare-mcp"],
      "env": {
        "FLARE_RPC": "https://flare-api.flare.network/ext/C/rpc",
        "FLARE_RPC_TESTNET": "https://coston2-api.flare.network/ext/C/rpc"
      }
    }
  }
}

Restart Claude Desktop. You can then ask things like "What's the FLR/USD price on Flare?" or "How much FXRP is minted right now?".

Quick Start — Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project) and add:

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

The same block works in any MCP client that supports stdio servers (VS Code, Windsurf, Zed, etc.). The env section is optional — the public Flare RPC endpoints are used by default.

Tools Reference

Every tool validates its input with zod and returns a clear error message (rather than crashing) when an RPC call or data source is unavailable. Thirteen tools are free; the two premium computed tools settle via x402 micropayments on Flare when the operator enables it (and are free otherwise).

§ Premium tools run free unless the server operator sets X402_ENABLED=true — see x402 payments.

† Requires an external data source configured via an environment variable (see below); on-chain aggregation of providers/history is impractical for a read-only stdio server. ‡ Best-effort: the MasterAccountController ABI is not yet published in the periphery artifacts, so this returns a has_account: false notice when it cannot resolve.

FDC attestation workflow

1. fdc_request_attestation  (type: Payment | AddressValidity | EVMTransaction,
                             source_chain: xrp | btc | doge | eth | flr | sgb)
     → verifier prepareRequest → fee quote → FdcHub.requestAttestation
     → { tx_hash, voting_round_id, abi_encoded_request }
2. wait ~90–180 s for the voting round to finalize
3. fdc_get_attestation_proof (voting_round_id, abi_encoded_request)
     → DA-layer proof → local keccak256 Merkle fold → must equal
       Relay.merkleRoots(200, round) read on-chain → verified response

Without FLARE_PRIVATE_KEY, step 1 returns mode: "prepared_only" with the encoded request, fee and FdcHub address so you can submit it with your own signer. The key, when provided, is only ever used to sign locally.

x402 payments (premium tools)

flare-mcp implements the x402 payment protocol adapted to MCP over stdio — the first MCP server whose paid tools settle on the chain they serve. HTTP's 402 status and X-Payment header map to tool results and a tool argument:

1. call a paid tool                → result: { x402_payment_required: true,
                                               accepts: [requirements] }
2. sign an EIP-3009 TransferWithAuthorization off-chain (gasless for payer)
3. retry the SAME call with        → x402_payment: base64(JSON payload)
4. server verifies the EIP-712 signature locally, checks the nonce on-chain,
   settles transferWithAuthorization on Flare, runs the tool
   → result includes { x402_payment_receipt: { tx_hash, ... } }

The built-in facilitator never holds funds: transferWithAuthorization moves tokens directly payer → payee; the operator key only pays gas to broadcast the client-signed authorization. Replay is blocked twice: EIP-3009 nonces are consumed on-chain, and settled nonces are additionally cached in-process.

Server-side setup (operator):

X402_ENABLED=true
X402_NETWORK=coston2            # mainnet additionally needs X402_ALLOW_MAINNET=true
X402_PAY_TO=0xYourPayeeAddress
FLARE_PRIVATE_KEY=0x...          # operator gas key for settlements
# optional: X402_TOKEN_ADDRESS, X402_PRICE_DEFAULT=0.001,
#           X402_PRICE_FASSETS_LIQUIDATION_SCANNER=0.005 (whole-token units)

Payment tokens (EIP-3009, verified on-chain 2026-07): Coston2 defaults to 0xce13911D4896200b543a61E4ae8E829E661Dd8EB (test USDT0); mainnet defaults to the official USD₮0 0xe7cd86e13AC4309349F30B3435a9d337750fC82D. Try the full agent flow with npx tsx scripts/x402-demo-client.ts.

Hub mode (hosted HTTP service)

Run flare-mcp as a network service instead of a local stdio process:

npx @dziuba0x/flare-mcp --http 8402         # or FLARE_MCP_HTTP_PORT=8402
# expose beyond localhost:
FLARE_MCP_HTTP_HOST=0.0.0.0 npx @dziuba0x/flare-mcp --http 8402

The REST endpoints use the standard x402 wire format (base64 JSON payload in X-Payment), so non-MCP agents and existing x402 clients can pay too. A Dockerfile ships in the repo:

docker build -t flare-mcp-hub . && docker run -p 8402:8402 \
  -e X402_ENABLED=true -e X402_PAY_TO=0xYou -e FLARE_PRIVATE_KEY=0x... flare-mcp-hub

Network Support

Contract addresses are never hardcoded — they are resolved at runtime through the Flare ContractRegistry at 0xaD67FE66660Fb8dFE9d6b1b4240d8650e30F6019 (the same address on all four networks). FDC verifier and Data Availability endpoints default to the Flare-hosted public services documented at dev.flare.network/network/overview.

Environment Variables

All are optional; the server runs against the public RPCs and Flare-hosted FDC services with no configuration.

See .env.example for a copy-paste template.

Development

# clone
git clone https://github.com/DziubaTechnology/flare-mcp.git
cd flare-mcp

# install
npm install

# run in watch/dev mode (no build step, via tsx)
npm run dev

# type-check and compile to dist/
npm run build

# offline test suite (recorded fixtures, no network needed)
npm test

# live acceptance checks against public RPCs (mainnet, Coston2, Songbird)
npx tsx scripts/live-check.ts

# run the compiled server
npm start

# open the MCP Inspector against the built server
npm run inspect

Stack: TypeScript (ESM, Node ≥ 18) · @modelcontextprotocol/sdk · viem · zod · @flarenetwork/flare-periphery-contract-artifacts.

The build emits an executable dist/index.js (with a #!/usr/bin/env node shebang) wired to the flare-mcp bin. Test individual tools without a client using the Inspector CLI, e.g.:

npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name get_ftso_feed \
  --tool-arg feed_id=FLR/USD --tool-arg network=mainnet

License

MIT © Dziuba Technology / Alan Dziuba.

Built by

Dziuba Technology — Alan Dziuba. Built on Flare Network. Contributions and issues welcome.