Flario

Flario

[CI] [npm version] [License: MIT] [Node] [Model Context Protocol]

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.

DELICTI: mandate before act

flario is the first effector that speaks DELICTI. A paying agent may add mandate_id (and optionally mandate_registry) to its x402 payload; the server binds it into the receipt (flario-receipt/2, field mandate_ref) so any third party can check the deed against an on-chain mandate and, with Flare's FDC as second witness, prove a receipt false or a budget exceeded.

Optional brake — set on the server:

DELICTI_REGISTRY=0x…        # MandateRegistry address on X402_NETWORKDELICTI_REQUIRE_MANDATE=1   # refuse payments that carry no mandate_id

With DELICTI_REGISTRY set, a payment whose mandate is not live, or whose payer is not the mandated agent, is refused before any funds move. Nothing here touches the EIP-712 authorization; a wrong mandate can never move funds, only get the deed refused or later proven false.

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 24 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 24 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: seven prompts, no Flare knowledge required

Tools answer questions. Prompts tell you what to ask in the first place. Flario ships seven, 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.

Watch Flare 2.0 arrive

Flare's confidential compute is being deployed right now, one network at a time, and Flare has not published an ABI for it — FlareTeeManager is absent from the periphery artifacts, alpha releases included. fcc_deployment_status reads it anyway, because the interesting facts do not need an ABI.

As of 1 September 2026 it reports:

Confidential compute is registered on: coston.Not yet on: mainnet, songbird, coston2.
coston: FlareTeeManager @ 0xc4885998f5D792ed88C5Af7a3AaCBe333f017658  ERC-2535 diamond, 18 facets, 198 selectors, 0 unrecognised  live state: 11 governance signers, machine allowlist revised 4 times  fdc2Hub()          -> 0x064C7B68B0e2BC87e7bE34e89741485Fcb48FA2F  (has code)  fdc2Verification() -> 0x21D3842E39A3b62ba15CD8A5D2ED5cEDea931502  (has code)

The capabilities come out of the selectors: Protocol Managed Wallets, remote attestation of TEE machines and their code hashes, multi-signature governance over the machine allowlist, randomness generated inside the enclave, and FDC V2 wiring.

Why selectors instead of function calls

A tool built on guessed function signatures breaks the moment Flare finalises the interface. Selectors are the routing table inside the diamond — they are facts on-chain, and a rename does not move them. So the tool reports what is exact (facets, selectors, addresses, wiring, governance state) and flags what is inferred: human-readable names come from a public signature database, and the report says so every time it prints one. All 198 resolved and are thematically coherent, which makes the mapping almost certainly right, but "almost certainly" is what gets printed rather than something firmer.

This is a testnet deployment of an unfinished system and anything in it can change. That is the point of a monitor rather than an integration.

Prove what an agent acted on

Every other tool here verifies a fact at the moment you ask, and then that verification evaporates — it survives as a sentence in a tool response nobody can re-check later. Evidence bundles close that gap.

evidence_bundle collects proof-carrying facts into one portable object. evidence_verify is the receiving end: it rebuilds every leaf from its own body, folds it through its Merkle proof, and compares the result against Relay.merkleRoots(protocol, round) read on-chain right then. The person verifying does not have to trust the agent that produced the bundle, this server, the data-availability layer, or any API. They need an RPC endpoint and nothing else.

Facts are verified before they go into a bundle. A fact that fails is refused, not flagged, because a bundle whose contents might be false is worse than no bundle at all. A Web2Json fact without expect_source is refused for the same reason — an unbound proof attests to whatever URL sits inside it.

The hash is not the security boundary

bundle_hash is tamper-evidence. It catches accidental corruption and casual edits, and an attacker who edits a bundle on purpose can simply recompute it. That is fine, because the hash was never what held. Here is the interesting case, run for real on mainnet:

podmieniona wartosc 7116 -> 21348, hash przeliczony na nowoverified: false | bundle_hash_intact: true | facts_failed: 1reason: the proof does not fold to the on-chain FTSO Scaling root

The attacker tripled a price and recomputed the hash so the integrity check passes. Verification still fails, because producing a Merkle proof that folds to a root Flare's validators already signed is not something you can do by editing a JSON file.

What a bundle does not prove

It does not prove the agent was honest about its reasoning, that these were the only facts it looked at, or that its conclusion follows from them. It proves that these specific facts were true, in these voting rounds. That is a narrower claim than "audit trail", and the narrowness is deliberate.

It is also a different claim from the one most verifiable-tool-call work makes. Attesting that a server executed correctly — via TEE, ZK over execution, or a server signature — still asks you to trust the operator or their hardware. This attests to the fact itself, against consensus, which needs a chain where the oracle is part of the protocol rather than a contract someone deployed.

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. Twenty-two 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 finalize3. 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 id2. wait ~90 to 180 s for the round to finalize3. 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 itdoes NOT come from the source you expected: attested host "swapi.info" is not inthe 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=trueX402_NETWORK=coston2            # mainnet also needs X402_ALLOW_MAINNET=trueX402_PAY_TO=0xYourPayeeAddressFLARE_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.gitcd flarionpm install
npm run dev      # watch mode via tsx, no build stepnpm run build    # type-check and compile to dist/npm test         # offline test suite, recorded fixtures, no networknpm start        # run the compiled servernpm 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.