Giving AI Agents Eyes on TON: Why Your Agent Needs an MCP Server, Not a Rate Limit

Ask an AI agent a simple question about TON — "did this wallet receive the jetton payment?" — and watch what it does. It resolves the address, fetches the account state, pulls the jetton wallet address, walks the transaction list, follows the internal messages, checks the transfer notification. One question, forty RPC calls, fired in about two seconds. That access pattern is why a TON MCP server is becoming the default way to connect agents to the chain, and why pointing your agent at a free public gateway is the fastest way to make it hallucinate.

This post covers what breaks, what the Model Context Protocol fixes, and what a good MCP tool surface for TON looks like — including the Claude TON integration config you can paste today.

Agents query in bursts. Gateways meter in seconds.

Public TON endpoints were designed for humans clicking through explorers, not for an AI agent blockchain workload. toncenter throttles anonymous users to 1 request per second. Tonkeeper's tonapi.io shared plans cap out at 50 RPS on a 10-second sliding window — exceed it and you get their proprietary error 228 — at $200/month for a shared instance ($50/month buys you 10 RPS).

A 1 RPS limit turns that forty-call jetton trace into a forty-second stall. Worse, agents don't degrade gracefully. When call 12 of 40 returns a 429, most agent loops do one of three things: retry and burn tokens, silently drop the data and reason over a partial picture, or confidently report an answer built on incomplete state. The third failure mode is the dangerous one. A rate limit doesn't just slow your agent down; it corrupts its view of the chain.

Raw public liteservers aren't a fix either. Anyone who has pulled the list from ton.org/global.config.json knows the greatest hits: "failed to send query to server: not ready", ADNL timeout error 652, stale nodes that can't even report their version. TON's own documentation recommends a dedicated liteserver for anything production-shaped. Agents are production.

MCP is the integration layer agents actually speak

The Model Context Protocol standardizes how an LLM discovers and calls external tools. Instead of teaching your agent to construct HTTP requests against a REST API (and to parse three different error formats when things go wrong), you hand it a set of typed tools with schemas. The model sees get_transactions(address, limit) and calls it. No prompt-engineered curl commands, no endpoint documentation stuffed into context.

For blockchain access this matters more than for most integrations, because the underlying protocol is genuinely hostile to LLMs. TON liteservers speak ADNL, a binary protocol, and clients verify every response against Merkle proofs. HTTP APIs like toncenter are just proxies over liteservers. An MCP server is the same idea, but shaped for a model: it handles ADNL, proof verification, address normalization, and BOC parsing, and returns structured JSON the model can reason over directly.

The tool surface a TON MCP server needs

A minimal but complete set, learned from watching what agents actually ask:

• get_balance — TON balance plus account status. The most-called tool by an order of magnitude.
• get_jettons — all jetton balances with metadata resolved, so the agent doesn't walk jetton wallet contracts itself.
• get_nfts — NFT items and collections owned by an address.
• get_transactions — paginated history with decoded message bodies, not raw BOCs.
• run_get_method — arbitrary get-method execution against any contract; the escape hatch that lets agents inspect STON.fi pools, DeDust vaults, or any of the contracts behind the 1000+ Telegram Mini Apps live on TON.
• resolve_dns — .ton domain resolution, because users give agents names, not raw addresses.

The archive question

The tool users love most is the one shared gateways can't serve: point-in-time state. "What was this wallet worth in January 2023?" requires an archive node, and running one yourself is a project — the official spec calls for 16 cores, 128 GB RAM, NVMe with 64k+ provisioned IOPS, and roughly 16 TB on ZFS with lz4 (20 TB uncompressed). Even restoring from the official dump at archival-dump.ton.org via curl | zstd -d | zfs recv, realistic bring-up is one to two weeks of download, import, and catch-up sync. TON has processed 3.27 billion transactions since its May 2021 genesis; an MCP server backed by an archive liteserver makes all of them queryable in one tool call.

Wiring it into Claude Desktop

MCP servers register in claude_desktop_config.json (Settings → Developer → Edit Config). A TON server entry looks like this:

{
  "mcpServers": {
    "ton": {
      "command": "npx",
      "args": ["-y", "@tonnode/mcp"],
      "env": {
        "TONNODE_API_KEY": "your-api-key"
      }
    }
  }
}

Restart Claude Desktop and the tools appear automatically. From there, "trace where this jetton transfer went" is a conversation, not an integration project. The same server works with any MCP-capable client — Claude Code, agent frameworks, your own orchestrator.

The backend still has to keep up

MCP fixes the interface; it doesn't repeal the rate limit underneath. If your MCP server proxies to a 1 RPS gateway, you've built a nicer-looking bottleneck. The network itself is not the constraint — TON runs ~0.4-second blocks with ~800 ms finality across 382 validators, and hit a CertiK-audited record of 104,715 TPS. The constraint is whatever endpoint your tools call.

Budget for burst capacity, not average load. An agent that idles for an hour and then fires 40 calls in two seconds needs headroom at the 95th percentile of its bursts. And if your agent broadcasts transactions or watches for incoming payments, remember that TON's mempool lives at the node level: pending external messages are visible to the node before validators seal them into a block — which makes mempool access a private-infrastructure feature by definition.

Where TONNode fits

TONNode runs private TON liteservers with an MCP server for AI agents on top — all the tools above, backed by dedicated lite and archive nodes rather than shared gateways. Plans start at $20/month for 10 RPS, archive-backed instances go up to 400 RPS, and pay-per-request pricing ($0.01/req lite, $0.02/req archive, bursts to 500 RPS) fits the idle-then-burst shape of agent traffic well. Provisioning takes under a minute, paid in GRAM or USDT. If you're giving an agent eyes on TON, details are at tonnode.io.