TON MCP: How to Give Your AI Agent Access to TON (Full Guide)

You have an AI agent — Claude in Cursor, a Codex script, a custom bot — and you want it to actually work with TON: check a wallet balance before sending, read transaction history, fetch a swap quote, prepare a cross-chain trade. But no matter how smart the agent is, it's blind: it has no eyes on the blockchain. The usual approach is to teach it to hit toncenter or tonapi.io over HTTP. That's where the pain starts: without a key you're capped at roughly one request per second; under load you're greeted with HTTP 429 Too Many Requests; the public liteservers from the global config reply not ready or drop on ADNL timeouts; and they simply don't keep deep transaction history. An agent that was supposed to "just check a balance" trips over infrastructure.

The fix isn't teaching the agent to call APIs by hand — it's giving it an MCP server for TON. Below is the full guide: what MCP is, why an agent needs it, how to connect for free with a single command, and what the 16 TONNode tools can do.

What MCP is and why an AI agent needs it

MCP (Model Context Protocol) is an open standard that lets AI agents call external tools. It's understood by Claude, Cursor, ChatGPT/Codex, and any other MCP client: you declare a set of tools, the agent sees their descriptions, and it decides on its own which one to call and with which parameters.

The analogy is simple: MCP is to an agent what a USB port is to a computer. A model on its own has no access to the network or the blockchain. Plug in an MCP server, though, and the agent gets a set of "sockets": read a balance, build a transaction, track a trade. You say "how much USDT is on wallet X" — the model figures out it needs the get_jetton_balance tool, fills in the address, and gets back a structured answer.

The difference from "just give the agent an HTTP endpoint" is fundamental. With a raw API, the agent has to hold in context how to shape requests, parse responses, and convert addresses and raw units. Every one of those is an opening for hallucination. MCP moves that logic to the server: the agent sees a get_balance tool with a clear signature and gets a ready-made answer. Fewer mistakes, fewer tokens in context, predictable behavior.

TONNode (tonnode.io) is exactly that — a ready-to-use hosted MCP server for TON (The Open Network). One endpoint, 16 tools covering reads, swaps, cross-chain, and wallets, running on top of TON's native protocol with no intermediate HTTP layers.

Why an agent needs a TON MCP server instead of public HTTP gateways

Fair question: why a dedicated server when public APIs like toncenter and tonapi.io exist? The problem is that public gateways are fine for one-off manual queries but were never built for an agent hammering out dozens of calls per minute in a loop.

• Rate limits and 429s. Without a key, toncenter and tonapi.io allow roughly one request per second and respond with HTTP 429 Too Many Requests beyond that. An agent running a "read state → decide → read more" loop hits the ceiling instantly — and hands the user an error instead of an answer.
• Public liteservers are unreliable. The liteservers from the global config (if you go to TON over ADNL directly) are shared and throttled. Under load they reply not ready, drop on ADNL timeouts, and don't store deep transaction history.
• A raw response is not an answer for an agent. Even a successful JSON payload often needs post-processing: deriving the jetton wallet address, rescaling raw units by decimals, converting an address between formats. Every step you hand off to the model is a potential mistake and wasted tokens.

An MCP server closes all of this: stable throughput tied to your key, computation done server-side, and a single interface with structured, ready-to-use answers. By the way, if you see people in chats mention "error 228" — that's a TON community meme number, not an API code; the actual rate-limit code is 429.

There's a detailed breakdown of the free route in a separate post: how to connect TON to an agent for free.

How to connect: free via npx, or a hosted key

There are two paths, and the first one is completely free.

Option 1. Local via npx (free, full read set)

The full set of read tools is available with no signup and no key. The @tonnode/mcp package is open source (MIT), lives on npm and GitHub (tonnode/mcp), and speaks TON's native ADNL protocol. Add this to your MCP client config:

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

Restart Claude Desktop, Cursor, or whatever client you use — the tools show up on their own. Step-by-step setup for specific clients is in the guide on connecting Claude and Cursor to TON.

Option 2. Hosted key (guaranteed throughput)

Once your agent runs in production and the request volume grows, you want your own key and a stable channel:

{
  "mcpServers": {
    "ton": {
      "type": "http",
      "url": "https://mcp.tonnode.io/mcp",
      "headers": {
        "Authorization": "Bearer tn_live_…"
      }
    }
  }
}

A free Hobby key is issued right after sign-in, no card required, and it unlocks all 16 tools — tonnode.io/dashboard?plan=hobby.

The 16 TONNode tools, by group

Every plan includes every tool — you only pay for throughput. Let's go through them group by group.

Reads (8 tools)

The foundation for any agent that observes the network without changing anything:

• get_masterchain_info — the masterchain head, the network's current tip.
• get_balance — GRAM balance of an address.
• get_account_state — account status, flags, last transaction.
• get_transactions — transaction history for an address.
• run_get_method — call any read-only get-method on a contract.
• get_jetton_balance — jetton balance (USDT, for example); the jetton wallet address is derived on-chain, so you don't need to know it upfront.
• parse_address — address conversion and validation (EQ/UQ/raw), works offline.
• get_jetton_info — jetton metadata: name, symbol, supply and, crucially, decimals. Decimals are critical for rescaling raw units: USDT has 6, most jettons have 9.

An example prompt for an agent with TONNode connected:

Check the GRAM and USDT balance of wallet UQ… and show the last 5 transactions.

The agent will call get_balance, get_jetton_balance (after fetching decimals via get_jetton_info), and get_transactions on its own — without a single manual HTTP request.

Swap (2 tools)

Swaps inside TON go through the Omniston protocol, which aggregates STON.fi and DeDust liquidity:

• get_swap_quote — a firm DEX quote for a GRAM ⇄ jetton pair.
• build_swap_tx — an unsigned swap transaction, ready to be signed via TonConnect.

Note the word "unsigned" — we'll come back to it in the non-custodial section.

Cross-chain (5 tools)

TON is always the source chain, and the trade runs through an atomic HTLC escrow — a mechanism where funds are locked against a secret's hash and released only when the conditions are met on both networks. Supported: Ethereum, Arbitrum, Base, BNB Chain, Polygon, Avalanche. TRON is not supported yet.

• get_crosschain_quote — a cross-chain swap quote.
• build_crosschain_swap_tx — an unsigned HTLC escrow transaction plus the secret.
• track_crosschain_swap — the trade's phases on both networks.
• disclose_crosschain_secret — reveal the secret to settle, after verifying readiness on-chain.
• build_crosschain_refund — pull funds back out of escrow if the trade stalls.

The HTLC scheme means the swap either completes atomically or comes back via refund — funds never get stuck with a middleman.

Wallet (1 tool)

• generate_wallet — creates a new TON wallet of version v3r2, v4, v5r1, or highload_v3 and returns the mnemonic, keys, and address. The server does not store the generated wallet — it's handed straight to you.

The full tool reference with parameters lives at tonnode.io/mcp.

Non-custodial by design: why the server never holds your keys

This is the fundamental distinction, and it's worth understanding before you let an agent anywhere near money.

The swap, cross-chain, and wallet-generation tools are strictly non-custodial. The TONNode server never signs transactions and never holds funds or private keys. When an agent calls build_swap_tx or build_crosschain_swap_tx, what it gets back is an unsigned TonConnect message — a transaction blueprint. The user's wallet signs it, not the server. Wallets from generate_wallet are likewise handed to you and never kept on the server.

An analogy: the MCP server is a navigator that plots the route and fills out the payment slip. But only you can hit "send" and attach the signature — you're the one at the wheel of your wallet. Even if the agent is compromised or simply wrong, it can't walk off with funds — all it ever holds is unsigned drafts.

A comparison with the official @ton/mcp from the TON Foundation is useful here. It's a strong, official package: it does reads, sending GRAM/jettons/NFTs, swaps via a DEX aggregator, NFT and DNS operations, and creating and importing agent wallets. But architecturally it's a custodial agent wallet with a split-key design: the agent itself holds the operator key and signs with it, while the user keeps the owner key. And it has no cross-chain — TON only. The trade-off is honest: the official package lets an agent spend funds autonomously and work with NFT/DNS; TONNode bets on non-custodial design, cross-chain, and a hosted option. The detailed breakdowns are in TONNode vs the official TON MCP and custodial vs non-custodial MCP.

Pricing and where to start

All 16 tools are available on every plan — only the throughput differs:

Plan	Price	Limit
Hobby	free forever	60 req/min
Pro	$29/mo	300 req/min
Scale	$199/mo	1200 req/min

You can pay for Pro and Scale in GRAM or USDT on TON via TonConnect, or in BTC/ETH/SOL and other currencies through an xRocket invoice in Telegram. The key is issued automatically once the payment settles. (In case you missed it: GRAM is Toncoin, renamed in June 2026 — the network itself is still called TON.)

A practical way to start:

1. Grab a free Hobby key — no card, issued right after sign-in, all 16 tools included: tonnode.io/dashboard?plan=hobby.
2. Drop in the hosted config (or start locally with npx -y @tonnode/mcp).
3. Give the agent its first read prompt — balance, account state, history — and confirm that 429s and not ready are no longer in your way.

Later, when you hit the ceiling in production, check out the pricing and the tool overview. Start with the free key and have your agent talking to TON in a couple of minutes.