Ankr Agent RPC — MCP Server

A Model Context Protocol server that gives AI agents token-efficient access to blockchain data through Ankr RPC.

Reads go out with the TORPC Accept-Token-Tier: 2 header. Tier 1 already renames the fields, turns hex into decimal and drops the service fields (logsBloom, cumulativeGasUsed, header roots). Tier 2 adds the ABI decode on top, so contract calls and event logs come back as named arguments.

A live run over 21 methods and 25 Ethereum mainnet blocks, token-weighted and counted with o200k_base over the full HTTP body, came out 48.4% smaller at tier 2 and 35.3% smaller at tier 1. Decode-heavy reads save the most: eth_getTransactionByHash 69.0%, eth_getTransactionReceipt 64.5%, eth_getBlockReceipts 60.3%, the block methods 40.4%, eth_getLogs 28.9%; scalar reads save 9–19%. Per-method figures: live-token-savings-2026-07-17.md.

---

Quick start

Get a free API key at ankr.com/rpc.

Hosted (no install)

The server runs at https://mcp.ankr.com/rpc. Send your key as the x-ankr-api-key header; each request carries the caller's own key, and the server holds no credential of yours.

{
  "mcpServers": {
    "ankr-agent-rpc": {
      "url": "https://mcp.ankr.com/rpc",
      "headers": { "x-ankr-api-key": "<YOUR_KEY>" }
    }
  }
}

Local (stdio)

{
  "mcpServers": {
    "ankr-agent-rpc": {
      "command": "npx",
      "args": ["-y", "@w3tech.io/agent-rpc-mcp"],
      "env": { "ANKR_API_KEY": "<YOUR_KEY>" }
    }
  }
}

That JSON goes in your client's MCP config: Claude Desktop (claude_desktop_config.json), Cursor, Windsurf, or any other MCP client. Cursor also accepts the command form:

env ANKR_API_KEY=<YOUR_KEY> npx -y @w3tech.io/agent-rpc-mcp

---

Tools

Raw RPC, TORPC tier 2

Tool	What it answers
getTransaction	transaction + receipt by hash, ABI-decoded
getLogs	event logs, decoded; wide block ranges are chunk-scanned and paged
getBlock	block header, optionally with decoded transactions

Indexed and mixed

Tool	What it answers
getBalances	native coin + ERC-20 balances with USD
getAccountBalance	balances across many chains at once
getWalletActivity	an address's transaction history, paged
getNFTs	NFTs held by an address
getTokenHolders	holders of an ERC-20, paged
getTokenPrice	USD price with chain, asset and as_of provenance
getTokenPriceHistory	historical price series for a token
getInteractions	which chains an address has touched, cross-chain
resolveContract	is-contract, best-effort ERC-20 metadata, EIP-1967 proxy
searchChain	resolve a tx/block hash, an address, or a block number
expandResult	continue any paged result from its cursor

Discovery and escape hatch

Tool	What it answers
listChains	supported chains, max TORPC tier, indexer availability
describeMethods	the param shape and a worked example per JSON-RPC method, plus whether your key may call it on that chain
rpcCall	any read method the routed tools do not cover

Sui

Sui is not an EVM chain and is not reached through the JSON-RPC proxy at all: a Sui call goes out over gRPC. getBalances, getBlock, getTransaction, getWalletActivity, getLogs and rpcCall take chain: "sui" and route themselves — getLogs reads Move events over a checkpoint range, filtered by emitting package or module, event type and sender. resolveContract and searchChain are built from eth_* calls Sui has never had and refuse there, naming the tool that answers instead. A Move event row is {contract, event, args}, the same shape an EVM tier-2 log has — but its args arrives at tier 0, decoded by the node rather than from an ABI, so on this path it is not evidence of a tier.

Eight tools serve what Sui has and an EVM chain does not:

Tool	What it answers
suiGetObjects	Move objects by id, batched, with their decoded fields
suiListOwnedObjects	every object an address owns, paged, filterable by Move type
suiListDynamicFields	tables, bags and dynamic object fields under one object's UID
suiGetPackage	the modules a published Move package declares
suiGetFunction	one Move function's signature
suiResolveName	a SuiNS name to its address, or an address to its name
suiSimulateTransaction	what a transaction would do, run against current state, never submitted
suiWatchEvents	Move events from the executed tip on, polled from a resumable cursor

That is the whole set: 25 tools.

What rpcCall will and will not do

rpcCall is a read and data escape hatch, never a wallet. It is a write denylist, not a read allowlist: it refuses transaction broadcast and signing, transaction building, node and dev-node administration, mutating verbs, and the node-operation half of geth's debug_* namespace — on every chain family — and forwards everything else.

It therefore keeps no list of permitted reads. Which reads exist is decided per chain by the endpoint's blockchain schema and by what your tenant may call, so a forwarded read can still come back refused (Method disabled, reason: restricted by blockchain schema). That refusal is the authoritative answer; listChains reports coverage.

Sign and send transactions with your own wallet or signer.

---

Reading a response

Two fields decide how to read every result, and an agent that skips them will misread output that is technically correct.

_meta.tier — the TORPC tier is negotiated per call and is not guaranteed. On the proxy path a response comes back at tier 0 (raw, undecoded, no args) when it is above the proxy's compression budget, and also when the method is one the proxy does not compress at all, such as eth_call, eth_getCode and eth_getStorageAt. Every successful response carries the tier actually applied in _meta.tier, so check it before looking for decoded fields; an error result carries _meta.error_code instead and no tier at all. Some tools additionally report tier_degraded: true in the body, with a note on how to narrow the request, when they asked for tier 2 on your behalf and got less. Not all of them do, so _meta.tier is the field to rely on. _meta.tier_source says who applied the tier, and the shape rule above is the proxy's alone: on the Sui gRPC path (tier_source: "local") a Move event row carries contract, event and args at tier 0, because the node decodes a Move struct itself.

Decoded amounts are raw base units, with no decimals applied. args.value: "41695680" on a 6-decimal token is 41.69568, not 41 million. Read the token's decimals with resolveContract before reporting a human number.

_meta.token_count is a real o200k_base count of the emitted text, not a chars/4 estimate. It is exact up to 256 KB of emitted text, which covers every display-capped response; above that it is extrapolated and the response carries _meta.token_count_estimated: true. Responses are minified JSON, so a model with a different tokenizer sees a similar but not identical number.

Tool inputs are strict: an unknown argument is rejected with a validation error rather than silently dropped, so a misspelled argument name is reported instead of ignored. Block numbers above 2^53 must be passed as strings, because a JSON number that large is not exact.

---

TORPC tiers

Tier	Meaning
0	passthrough — standard JSON-RPC
1	field rename, hex → decimal, and the service fields dropped: logsBloom, cumulativeGasUsed, contractAddress, type, the header roots
2	tier 1 plus the ABI decode — each log becomes {contract, event, args}, calldata becomes a decoded function with named args

Negotiation is by header: Accept-Token-Tier: 0|1|2 on the request, Token-Tier on the response. The proxy applies the requested tier only while the response stays inside its compression budget, and that budget is internal to the proxy — so this server never predicts the tier, it detects the applied one and reports it.

On a JSON-RPC batch that header describes the array, not any one element: a response array carries a single Token-Tier, and its value is the minimum tier applied across the elements. v1 defines no per-element tier signal, elements may sit above that floor, and a client reads each element's own tier from the shape the proxy left on it — renamed fields and decimal strings for tier 1, event/args for tier 2 — rather than from the header. So the header is a floor and a signal that a transform was applied; which methods reach tier 2 is declared per method in the descriptor at https://mcp.ankr.com/.well-known/torpc.json, which also ships in the npm package at static/.well-known/torpc.json.

Specification: w3tech/torpc, released under CC0-1.0, with the TORPC docs page as the narrative version. The reference decoder is published as @w3tech.io/torpc-decoder (Apache-2.0); its source and the benchmark harness live in w3tech/torpc-js, under codec/. The EVM tier-1 and tier-2 rules are normative in the spec today; the conformance suite is a scaffold, so no implementation, this one included, claims conformance yet.

---

Discovery

Two machine-readable documents describe this deployment. Both are public, carry no credential, and are readable cross-origin.

Document	Served at
TORPC descriptor: protocol version, negotiation headers, tier meanings, method lists	mcp.ankr.com/.well-known/torpc.jsonrpc.ankr.com/.well-known/torpc.json
Agent card: an ERC-8004 registration file naming who answers, and at which MCP endpoints	mcp.ankr.com/.well-known/agent-card.jsonrpc.ankr.com/.well-known/agent-card.json

Both ship in this package under static/.well-known/, and the served copy is the deployment's own statement: a packaged copy can lag it. The card states x402Support: true, because /rpc without a key takes per-call payment over x402, and claims no on-chain registration and no trust mechanism, because there is none to claim.

---

Supported chains

Ethereum, BSC, Polygon, Arbitrum, Optimism, Base, Avalanche and more, plus testnets. Indexed tools cover a wider set than the raw-RPC tools.

Call listChains for the live matrix rather than trusting a list in a README — coverage changes without a release here.

---

Managing your Ankr account

A second, separate MCP surface at https://mcp.ankr.com/mcp covers account management — API keys, allowlists, usage, billing reads and team membership — and authenticates with OAuth rather than an API key. Sign in when your client prompts. An RPC API key is not management authority and will be refused there.

---

Links

• API keys and plans: ankr.com/rpc
• Documentation: Agent RPC and account management on ankr.com/docs
• TORPC specification: w3tech/torpc (CC0-1.0), narrated on the TORPC docs page
• TORPC decoder: @w3tech.io/torpc-decoder (Apache-2.0), source in w3tech/torpc-js under codec/
• npm package: @w3tech.io/agent-rpc-mcp
• Discovery documents: TORPC descriptor and agent card

License

MIT — see LICENSE.