TONNode vs the Official @ton/mcp: an Honest TON MCP Comparison

@ton/mcp vs TONNode: an honest comparison — and the first question is: who holds the keys?

This comparison of two TON MCP servers starts not with a feature list but with a single security question. Picture this: you've given Claude or Cursor access to TON. The agent reads balances, assembles swaps, calls get-methods. Everything works — right up to the moment a transaction needs a signature. And then at 3 a.m., off a sloppy prompt (or an instruction planted in some page it happened to read), the agent decides to "optimize the portfolio" and signs the transaction itself. The funds are gone. You find out in the morning.

That's not a scare story — it's the direct consequence of one architectural choice: does the agent sign with its own key, or does the signature always stay with the user's wallet? This is exactly where the two mature MCP servers for TON part ways — the official @ton/mcp from the TON Foundation and TONNode. Both give an agent real hands on-chain. Let's compare them honestly, without talking either one down — both are legitimate designs, for different jobs.

Why compare at all: two different takes on MCP for TON

MCP (Model Context Protocol) is the standard that lets AI agents (Claude, Cursor, ChatGPT/Codex, any MCP client) call tools. For TON that means the agent gets a set of functions like get_balance or build_swap_tx and invokes them on its own as the conversation unfolds, whenever it sees fit.

The difference between @ton/mcp and TONNode isn't the command list — it's the philosophy. An analogy: @ton/mcp is like handing your assistant a corporate card with a limit: they pay on their own, fast and autonomously, but the card is in their hands. TONNode is the assistant who prepares the payment order and puts it on your desk for signing: nothing moves until your wallet signs. Both models work. The question is which job you're hiring for.

If you'd rather start with the theory, there's a separate deep dive into custodial vs non-custodial MCP. Here we'll compare the specifics.

The official @ton/mcp: a custodial agent wallet with NFT and DNS

@ton/mcp is the official TON Foundation package, and that is its strength: backing from the network's own team, predictable development, and the status of a reference implementation.

Architecturally it's a custodial agent wallet with a split-key model:

• the operator key lives with the agent. The agent uses it to sign transactions itself, with no involvement from you.
• the owner key stays with the user, as a second layer of control over the wallet.

What it does out of the box:

• reading network state, accounts, balances;
• sending GRAM, jettons and NFTs (the agent signs on its own);
• swaps through a DEX aggregator;
• creating and importing agent wallets;
• reading NFTs and DNS — something TONNode doesn't have yet, and that's an honest advantage of the official package.

It runs locally, over HTTP, or serverless. One limitation by design: TON only, no cross-chain.

The headline here is autonomy. The agent spends by itself, with no human in the signing loop. For scenarios like "let the agent pay for subscriptions, gas and micro-tasks on its own", that's exactly what you want. But the same autonomy means the working key that controls the funds sits on the agent's side — so a prompt injection or a model hallucination can turn into real spending.

TONNode: a non-custodial MCP with cross-chain and a hosted option

TONNode is a hosted MCP server for TON (tonnode.io) with exactly 16 tools. The core invariant fits in one sentence:

The server never signs and never holds funds or private keys. The swap, cross-chain and wallet tools return unsigned TonConnect messages. The user's wallet signs them.

There is no moment at which the server could walk off with your funds, because it physically has no key. Let's go through the tools group by group.

Reading (7+1)

Covers the day-to-day:

get_masterchain_info — masterchain head
get_balance          — GRAM balance
get_account_state    — status, flags, last transaction
get_transactions     — transaction history
run_get_method       — any read-only contract get-method
get_jetton_balance   — jetton/USDT balance (jetton wallet resolved on-chain)
get_jetton_info      — jetton metadata: name, symbol, decimals, supply
parse_address        — EQ/UQ/raw conversion, offline

get_jetton_info returns decimals — you need them to convert raw units: USDT has 6, most jettons have 9.

Swap (2)

Runs through the Omniston protocol — aggregated liquidity from STON.fi and DeDust:

• get_swap_quote — a firm GRAM⇄jetton quote;
• build_swap_tx — an unsigned transaction, ready for TonConnect.

Cross-chain (5)

The thing the official package doesn't have at all. Atomic HTLC escrow where TON is always the source chain:

• get_crosschain_quote — a quote;
• build_crosschain_swap_tx — an unsigned HTLC escrow transaction + the secret;
• track_crosschain_swap — the deal's phases on both networks;
• disclose_crosschain_secret — reveal the secret to settle, after verifying readiness on-chain;
• build_crosschain_refund — recover funds from escrow if the deal stalls.

Supported networks: Ethereum, Arbitrum, Base, BNB Chain, Polygon, Avalanche. TRON is not supported yet. For a step-by-step walkthrough of one of these deals, see the write-up on the first cross-chain transfer by a TON agent.

Wallet (1): generate_wallet creates a v3r2/v4/v5r1/highload_v3 wallet and hands the mnemonic, keys and address to the user — the server does not store them.

What TONNode does not have yet: NFT and DNS tools — they're on the roadmap. If today's task is reading NFT collections or resolving .ton domains, that's the official package's territory. Also note: TONNode has no direct "send/transfer" tool for GRAM or jettons either. The only unsigned-transaction builders are build_swap_tx, build_crosschain_swap_tx and build_crosschain_refund — meaning funds can only move as part of a swap, a cross-chain deal, or an escrow refund. There is no arbitrary "send" here, by design.

Comparison table: @ton/mcp vs TONNode

Criterion	Official @ton/mcp	TONNode
Who signs	The agent itself (operator key, split-key)	The user's wallet (the server never signs)
Model	Custodial	Strictly non-custodial
Autonomous spending	Yes	No (by design)
Direct GRAM/jetton transfers	Yes, autonomously	No dedicated tool; transfers only happen inside a swap/cross-chain deal as an unsigned tx
Swap	DEX aggregator	Omniston (STON.fi + DeDust)
Cross-chain	No (TON only)	Yes, HTLC escrow to 6 networks
NFT / DNS	Yes (reading)	On the roadmap
Wallet generation	Create/import agent wallets	v3r2/v4/v5r1/highload_v3, keys stay with the user
Deployment	Local / HTTP / serverless	Local (npx) + hosted endpoint
Status	Official, TON Foundation	Independent, open source (MIT)

The key fork in the road: who holds the agent's keys

Everything else is just detail. The real choice comes down to one question: are you comfortable with the agent signing transactions on its own?

With @ton/mcp, the operator key lives with the agent — which means the agent can spend funds off a prompt, with no second factor in the form of a human signature. That's powerful for autonomy and risky under prompt injection or hallucination: a compromised context = potentially spent funds.

With TONNode, a signature physically cannot happen on the server. Even if the agent "loses its mind" and calls build_swap_tx with absurd parameters, the most it gets back is an unsigned transaction object. Until the user's wallet confirms it, nothing moves. That's an architectural guarantee, not a policy.

Neither approach is "better" in the abstract — they're about different levels of trust in agent autonomy.

When to pick the official @ton/mcp, and when TONNode

Pick @ton/mcp if:

• you need autonomous spending — the agent pays and signs on its own, no human in the loop;
• you work strictly inside TON and don't need cross-chain;
• you need NFT and DNS today;
• the official Foundation status of the package matters to you.

Pick TONNode if:

• only the user's wallet — never the agent — should control the money; the pattern is broken down in the piece on non-custodial swaps for TON agents;
• you need TON⇄EVM cross-chain (Ethereum, Arbitrum, Base, BNB Chain, Polygon, Avalanche);
• you want swaps through Omniston's aggregated liquidity;
• you need a hosted endpoint with guaranteed throughput, not just a local install.

This isn't "better vs worse" — these are different tools. The approaches aren't mutually exclusive either: many teams keep both servers in their config — the official one for NFT/DNS and autonomous tasks, TONNode for non-custodial swaps and cross-chain.

How to hook up each one

If you're new here, start with the general introduction — the MCP for TON guide.

TONNode locally — free, the full read set

The @tonnode/mcp package is open source (MIT, on npm and GitHub tonnode/mcp) and speaks TON's native ADNL protocol with no HTTP middlemen:

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

TONNode hosted — your own key, guaranteed throughput

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

Once it's connected, you can give the agent plain-text tasks — it will pick the tools itself:

Check my USDT balance on wallet EQ… using get_jetton_balance.
Then get a get_swap_quote for swapping 50 USDT into GRAM
and build the transaction with build_swap_tx.
Don't send the transaction — return it to me to sign in my wallet.

The agent will call get_jetton_balance → get_swap_quote → build_swap_tx and hand back an unsigned TonConnect message. Money only moves after confirmation in the wallet.

A cross-chain task reads just as naturally:

Build a swap of 100 GRAM from TON into USDC on Base.
Get a get_crosschain_quote, then build_crosschain_swap_tx.
Keep the secret safe and track the status with track_crosschain_swap.

All 16 tools are available on every plan — you only pay for throughput: Hobby — free forever, 60 requests/min; Pro — $29/mo, 300 requests/min; Scale — $199/mo, 1200 requests/min. The Hobby key is issued right after sign-in, no card required.

The official @ton/mcp

@ton/mcp installs per the TON Foundation's instructions and runs locally, over HTTP, or serverless. During initial setup, an agent wallet with an operator key is created or imported for the agent. Keep the custodial model in mind: think through spending limits ahead of time, and decide which funds the agent will actually get access to.

Bottom line

@ton/mcp is the official custodial agent wallet: split-key, autonomous spending, NFT and DNS, TON only. TONNode is a non-custodial server with 16 tools: the server never signs, and it adds cross-chain to 6 networks plus a hosted option. The difference is honest and architectural — it's about who you trust with the right to sign. Whoever signs sets the risk profile.

A tool-by-tool comparison lives on the TONNode vs the official MCP page. To try the non-custodial approach right now, on a free Hobby key with no card, go here: tonnode.io/dashboard?plan=hobby.