Flario MCP Server

Flario

An MCP server for Flare Network. Flario gives an AI agent (in Claude, Cursor, VS Code, or any Model Context Protocol client) plain-language access to Flare's enshrined protocols: FTSO price feeds, FDC cross-chain attestations, and FAssets. It also gives the agent a wallet. Premium tools are paid per call with x402 settled on Flare, and every payment comes back with a receipt the chain itself can prove.

Install it with npx flario, or run it as an HTTP hub. It works against the public Flare RPCs out of the box, needs no account or key for reads, and never holds or forwards funds.

Flario covers the whole enshrined stack: FTSO prices (including proof-carrying anchor feeds), FDC attestation workflows with local Merkle-proof verification, deep FAssets state (per-agent collateral, liquidation risk, system totals, the redemption queue), a Flare portfolio read (delegation, vote power, claimable rewards), Songbird and Coston support, and a watcher for Flare Confidential Compute contracts. Reads are trust-minimized: FDC and FTSO proofs are checked locally against the on-chain Relay root, never taken from an API on faith. The one write, fdc_request_attestation, only submits a transaction if you set FLARE_PRIVATE_KEY; otherwise it hands you a prepared request to sign yourself.

This is complementary to Flare's official MCP server, not a replacement. Their server (dev.flare.network/mcp) does documentation search, so it gives an agent knowledge. Flario gives an agent hands and a wallet: it calls the enshrined protocols and lets the agent pay for computed results, with receipts the chain can verify. Use both.

Where this sits in the x402 ecosystem

Flario speaks the standard x402 wire format, so it is not a private dialect. Payment requirements come back in the usual shape, the payment payload travels base64-encoded in the X-Payment header on the HTTP hub, and the settlement summary comes back in X-Payment-Response. An existing x402 client can pay a Flario endpoint without knowing anything about MCP, and an MCP agent can pay without knowing anything about HTTP.

What Flario adds on top is a proof layer. In a typical x402 deployment, the client learns that a payment settled because the facilitator says so and points at a transaction. Because Flare has a data connector enshrined in the chain, Flario can go further: fdc_verify_settlement obtains an FDC attestation over the settlement transaction, verifies the Merkle proof locally against the on-chain Relay root, and binds it to the actual ERC-20 transfer, so the receipt stands on its own without trusting the facilitator. That step depends on a protocol built into the chain, which is why it is hard to port elsewhere.

---

Why Flario

• It goes deep on the protocols that are built into Flare. FTSO, FDC, and FAssets are enshrined in the chain, and so are Flario's 21 tools. A generic multi-chain MCP server can't reach any of this, and the depth doesn't port to another chain.
• Answers carry a proof, so you don't have to take my word for it. Prices and cross-chain facts come with a Merkle proof that Flario checks locally against the on-chain root. An agent, or even a smart contract, can rely on the answer without trusting any API.
• Agents can pay, and they get a receipt. Premium tools settle per call over x402 on Flare, and each payment returns a portable receipt that Flare's own FDC can prove, not just the facilitator's word for it. No other chain in the x402 ecosystem can do that today.
• Self-hostable, no custody. It runs on public RPCs, asks for no account or key to read data, and never touches your funds.

---

Examples

Once Flario is in your MCP client (see Install), you just ask in plain language:

A proof-carrying price comes back with the value and a proof the agent can verify on its own (trimmed):

{
  "verified": true,
  "verification": "Local: keccak256(abi.encode(feed body)) folded through the Merkle proof equals Relay.merkleRoots(100, round) read on-chain.",
  "name": "FLR/USD",
  "price": 0.006786,
  "voting_round_id": 1402671,
  "merkle_root": "0x...",
  "proof": ["0x...", "0x..."]
}

---

Install

Claude Desktop

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

{
  "mcpServers": {
    "flario": {
      "command": "npx",
      "args": ["-y", "flario"],
      "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, then ask something like "What's the FLR/USD price on Flare?" or "How much FXRP is minted right now?".

Cursor

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

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

The same block works in any MCP client with stdio support (VS Code, Windsurf, Zed, and so on). The env block is optional, since the public Flare RPCs are used by default.

Check it works (no client, ~10 s)

# List all 21 tools straight from the published package:
npx -y @modelcontextprotocol/inspector --cli npx -y flario --method tools/list

# Or call one, a proof-carrying FLR/USD price on mainnet:
npx -y @modelcontextprotocol/inspector --cli npx -y flario \
  --method tools/call --tool-name get_ftso_anchor_feed \
  --tool-arg feed_id=FLR/USD --tool-arg network=mainnet

---

Start here: five prompts, no Flare knowledge required

Tools answer questions. Prompts tell you what to ask in the first place. Flario ships five, and they show up in your MCP client's prompt list once it is connected — in Claude Desktop, the + menu in the message box.

Every prompt instructs the model to run the calls for real against the live network and then explain what happened, so you end up with actual numbers and a mental model at the same time. They are deliberately written to admit when something is not live yet rather than talk around it.

Tools

Every tool validates its input with zod and returns a clear error instead of crashing when an RPC call or data source is down. Nineteen tools are free. The two premium tools settle via x402 on Flare when the operator turns it on, and are free otherwise.

Notes on a few tools:

• Premium tools run free unless the operator sets X402_ENABLED=true. See How payments work.
• get_ftso_providers needs an external indexer endpoint (set with an env var below). Aggregating providers on-chain isn't practical for a read-only stdio server.
• get_smart_account_info is best-effort. The MasterAccountController ABI isn't published in the periphery artifacts yet, so it returns a has_account: false notice when it can't resolve.

The FDC attestation flow

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 to 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, the fee, and the FdcHub address, so you can submit it with your own signer. When the key is set, it only ever signs locally.

---

How payments work (x402)

Flario implements the x402 payment protocol over MCP. As far as I know it's the first MCP server whose paid tools settle on the same chain they serve. HTTP's 402 status and X-Payment header map onto 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 the payer)
3. retry the SAME call with         -> x402_payment: base64(JSON payload)
4. the server checks the EIP-712 signature locally, checks the nonce on-chain,
   settles transferWithAuthorization on Flare, runs the tool
   -> result includes x402_payment_receipt (settlement summary) and
      x402_receipt (a portable, ZK-ready receipt; see RECEIPT_SPEC.md)

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

Every paid call returns a portable x402_receipt. It's a fixed-schema, self-describing record where the payer shows up only as a Poseidon commitment, never in plaintext, with a keccak256 receipt_hash any holder can recompute to check for tampering. A payer can blind the commitment with an optional commitment_salt in the payment payload. Full spec: RECEIPT_SPEC.md.

---

Prove any web fact (Web2Json)

FDC's Web2Json type fetches JSON from a URL, runs a jq filter over it, and returns ABI-encoded data. That means any public API can become a fact a smart contract is able to check. Flario wraps the whole loop for an agent:

1. fdc_web2json_request  (url + post_process_jq + abi_signature)
     -> a Flare verifier validates it and quotes the fee
     -> submit to FdcHub (your key), get a voting round id
2. wait ~90 to 180 s for the round to finalize
3. fdc_verify_web2json  (voting_round_id + abi_encoded_request + expect_source)
     -> Merkle proof checked locally against Relay.merkleRoots(200, round)
     -> attested URL bound to the source you expected
     -> payload decoded with the request's own ABI signature

Why expect_source matters

Flare's own guide is blunt about the trap (URL parsing security):

A valid FDC proof only guarantees the data came from the URL in the proof. It does not guarantee the URL is trustworthy.

So a proof that passes Merkle verification is only half the story. An attacker can stand up their own endpoint, get a completely valid attestation for it, and hand you that proof. fdc_verify_web2json therefore does both jobs: it verifies the proof, and it binds the proof to the source you actually meant to use.

{
  "expect_source": {
    "hosts": ["api.coingecko.com"],
    "path_prefix": "/api/v3/simple/price",
    "require_https": true,
    "http_method": "GET"
  }
}

If the attested URL does not match, the call fails loudly even though the cryptography is fine. Leave expect_source out and you still get the proof, but the response is marked source_bound: false with a warning, because that is the path an attacker can walk through.

Binding uses a real URL parser instead of string prefix matching, which closes three bypasses that naive checks miss:

Each of these has a test in test/web2json.test.ts.

Here is a real verified response from Coston2, using the same API Flare's own Web2Json guide uses (trimmed):

{
  "verified": true,
  "source_bound": true,
  "verification": "Two checks passed. The Merkle proof folds to Relay.merkleRoots(200, round) read on-chain, and the attested request matches the source you expected (protocol, host, path, method).",
  "voting_round_id": 1409295,
  "source": {
    "url": "https://swapi.info/api/people/3",
    "http_method": "GET",
    "parsed": { "protocol": "https", "host": "swapi.info", "path": "/api/people/3" }
  },
  "data": { "name": "R2-D2", "height": "96", "mass": "32" }
}

Ask for the same proof while expecting a different host and the call fails on purpose, even though the cryptography is perfectly valid:

The FDC proof is VALID (Merkle-verified against the on-chain Relay root) but it
does NOT come from the source you expected: attested host "swapi.info" is not in
the expected list (api.coingecko.com). Treat this data as untrusted.

FDC-verified settlement (the part I'm proudest of)

A receipt claims a payment settled. Flare can prove it did, using the chain's own enshrined data connector. fdc_verify_settlement takes a settlement tx, gets an FDC EVMTransaction attestation over it, verifies the Merkle proof locally against the on-chain Relay root, and then binds the attestation to the payment: it confirms the attested transaction really contains an ERC-20 Transfer of the asset to the payee for at least the amount. The result is a receipt whose fdc_attestation_ref makes the settlement provable without trusting the facilitator. No other chain in the x402 ecosystem produces a protocol-level receipt like this. The tool never submits a transaction itself (the attestation request is permissionless, so the holder submits it), which means a hosted hub can't be tricked into burning gas.

Operator setup:

X402_ENABLED=true
X402_NETWORK=coston2            # mainnet also 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, checked on-chain in July 2026): Coston2 defaults to 0xce13911D4896200b543a61E4ae8E829E661Dd8EB (a test USDT0), and mainnet defaults to the official USD₮0 at 0xe7cd86e13AC4309349F30B3435a9d337750fC82D. You can walk the whole agent flow with npx tsx scripts/x402-demo-client.ts.

---

Run it as a hub

You can run Flario as a network service instead of a local stdio process:

npx flario --http 8402         # or FLARIO_HTTP_PORT=8402
# to expose it beyond localhost:
FLARIO_HTTP_HOST=0.0.0.0 npx flario --http 8402

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

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

---

Networks

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

Configuration

Everything here is optional. The server runs against the public RPCs and Flare-hosted FDC services with no config at all.

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

---

Security posture

This thing touches money, so the defaults lean paranoid.

• No custody, anywhere. Flario never holds or forwards funds. x402 settlement moves tokens straight from payer to payee inside transferWithAuthorization; the operator key only pays gas to broadcast an authorization the client already signed.
• Verify, then bind. Every proof-consuming tool does two things, not one. A Merkle proof that checks out is necessary but not sufficient, so fdc_verify_settlement binds the attestation to the actual ERC-20 Transfer, and fdc_verify_web2json binds it to the source you expected. A valid proof for the wrong thing is rejected with a precise reason.
• Submission is off by default in hub mode. In stdio mode you are the only caller, so spending your own gas on an attestation request is what you asked for. In hub mode anyone who reaches the port is a caller, and the operator key exists to settle x402 payments, so letting a stranger trigger paid on-chain requests would drain it. Hub mode therefore refuses on-chain submission and returns the prepared request instead, unless the operator sets FLARIO_HUB_ALLOW_SUBMIT=true.
• Keys stay local. FLARE_PRIVATE_KEY is read from the environment, used to sign in-process, and never logged or transmitted anywhere except as an already-signed transaction to the RPC you configured.
• Replay protection is doubled. EIP-3009 nonces are consumed on-chain, and settled nonces are also cached in-process to close the window between broadcast and on-chain visibility.
• No per-user data is collected or stored. There is no analytics, no database, no transaction-graph logging. Receipts belong to whoever holds them.
• Contract addresses are never hardcoded. They resolve at runtime through the Flare ContractRegistry, and every protocol constant in the source cites the Flare doc it came from.

Found something? Open an issue, or reach me privately if it's sensitive.

---

Development

git clone https://github.com/dziuba0x/flario.git
cd flario
npm install

npm run dev      # watch mode via tsx, no build step
npm run build    # type-check and compile to dist/
npm test         # offline test suite, recorded fixtures, no network
npm start        # run the compiled server
npm run inspect  # open the MCP Inspector against the built server

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

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

The build emits an executable dist/index.js (with a #!/usr/bin/env node shebang) wired to the flario bin. You can test a single tool without a client using the Inspector CLI:

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 on Flare Network. Issues and contributions welcome.