The First TON MCP That Lets AI Agents Move Value Across Chains

A DeFAI agent on TON: why reading the blockchain isn't enough

Your AI agent can answer questions about TON — wallet balance, contract status, transaction history. Then the user types: "I've got 500 USDT on TON and I want to open a position on Base." And the agent stops dead. It sees everything and can do nothing. Between "read the blockchain" and "move value" there's a gap that no ordinary read-only MCP can clear. A read-only agent is a dashboard with a chat window. DeFAI (DeFi + AI) starts where the agent moves value instead of just looking at it.

The second wall is trust. Most "smart wallets for agents" are custodial: for the agent to send anything, someone has to hold a key and sign. For an autonomous bot, that means a private or operator key sitting somewhere outside your control. For production with other people's money, that's a non-starter.

TONNode is a hosted MCP server for TON (see tonnode.io) with exactly 16 tools: reads, swaps, cross-chain, and wallet generation. The key point: the swap, cross-chain, and wallet tools are strictly non-custodial. The server never signs and never holds funds or private keys — it returns unsigned TonConnect messages that the user's wallet signs. That's what a TON cross-chain MCP looks like when you don't have to compromise on key control.

For an action to be safe, two things have to be true:

• The agent prepares the transaction but never signs it. The signature comes from the user's wallet via TonConnect. The server never touches the keys.
• The agent can operate beyond a single chain. Value in crypto lives across several networks at once, and "TON only" is half the job.

TONNode does both. Here's how to assemble a real DeFAI agent out of these tools.

Non-custodial swaps: get_swap_quote and build_swap_tx via Omniston

Swapping in TONNode comes down to two tools with a clean separation of duties: quote first, then build.

• get_swap_quote — a firm GRAM⇄jetton quote via the Omniston protocol, which aggregates liquidity from STON.fi and DeDust. The agent gets the best price across the two largest DEXes at once instead of guessing which one is cheaper.
• build_swap_tx — builds an unsigned swap transaction, ready for TonConnect. This step is the essence of non-custodial design: the server hands over a message, and the user's wallet signs it.

The analogy is simple. get_swap_quote is the price board at an exchange counter. build_swap_tx is the filled-out receipt you read and sign yourself. The teller (the server) never reaches into your wallet.

In a conversation with the agent it looks like this:

User: swap 100 GRAM to USDT, show me the rate before confirming

Agent → get_swap_quote (GRAM → USDT, 100)
Agent: you'll get ≈ X USDT at rate Y (Omniston route). Build the transaction?

User: yes

Agent → build_swap_tx
Agent: done, sign it in your wallet ↓ (TonConnect)

One detail that matters for correct amounts: jettons are stored in raw units, and the conversion depends on decimals. USDT has decimals = 6; most jettons use 9. Before showing any balance or amount, the agent should call get_jetton_info (jetton metadata: name, symbol, decimals, supply) and get_jetton_balance (jetton balance; the jetton wallet is derived on-chain). Otherwise the agent will show the user "50000000" instead of "50".

Keys never leave the user's device at any step. For a deeper dive into this scheme, see non-custodial swaps for agents.

Cross-chain MCP for TON: atomic HTLC escrow and a path to 6 EVM chains

Now for the part no other TON MCP has: cross-chain swaps from TON into EVM networks without a custodial bridge. TONNode does it with an atomic HTLC escrow (Hashed TimeLock Contract).

The mechanics work like a deal through a safe-deposit box with two locks:

1. Funds are locked in escrow contracts on both chains under the same secret hash.
2. Until the secret is revealed, the money goes nowhere.
3. Revealing the secret unlocks both sides at once — either the deal completes entirely, or it doesn't happen at all. There is no in-between "money left but never arrived" state.
4. If the counterparty stalls, a timeout returns the funds to their owner.

These are the only supported networks, and TON is always the source:

• Ethereum
• Arbitrum
• Base
• BNB Chain
• Polygon
• Avalanche

TRON is not supported yet — and it's important to say so honestly, so the agent never promises the impossible.

The critical non-custodial detail here: build_crosschain_swap_tx returns both the unsigned HTLC escrow transaction and the secret — the secret stays with the user/agent, not on the server. Revealing the secret is a separate, explicit step taken only after verifying readiness on-chain. The full mechanics are covered in the TON → Ethereum cross-chain swap write-up.

Five cross-chain tools: quote, build, track, disclose, refund

A cross-chain trade isn't a single button — it's a state machine. Each state has its own tool:

1. get_crosschain_quote — a cross-chain quote: how much the user receives on the target chain, fees, and the route.
2. build_crosschain_swap_tx — an unsigned HTLC escrow transaction plus the secret. The user's wallet signs the transaction; the secret stays with the user.
3. track_crosschain_swap — the trade's phases on both chains: is the TON escrow locked, has the matching lock appeared on the EVM side, has the secret been revealed, has settlement completed.
4. disclose_crosschain_secret — reveal the secret for settlement, but only after verifying readiness on-chain. This is the guard against revealing the secret too early and losing control of the trade.
5. build_crosschain_refund — builds a transaction that pulls funds back out of escrow if the trade stalled and the timeout has fired.

The full lifecycle of a trade

Here's the flow the agent runs from quote to settlement or refund:

get_crosschain_quote        → quote for TON → Base
build_crosschain_swap_tx    → unsigned HTLC escrow tx + secret
   (the user signs the escrow with their own wallet)
track_crosschain_swap       → wait for the counterparty side to be ready
disclose_crosschain_secret  → reveal the secret, settlement runs
   ── if the trade stalls ──
build_crosschain_refund     → refund from escrow

Note that the refund is built into the design, not bolted on. build_crosschain_refund is exactly what makes this construction safe for an autonomous agent: even if something goes wrong, funds don't get stuck — there's a deterministic path back. These five tools turn the "scary bridge" into a predictable step-by-step process.

TONNode's moat: non-custodial + cross-chain + hosted

Let's compare honestly with the official package. @ton/mcp from the TON Foundation is a custodial agent wallet with a split-key scheme: the agent holds the operator key, the user holds the owner key, and the agent signs on its own. It can do a lot — reading chain data, sending GRAM/jettons/NFTs, swapping via a DEX aggregator, working with NFTs and DNS, creating and importing agent wallets — and it's official. Those are real strengths, and there's no point downplaying them.

But two limitations matter:

• It's custodial — the operator key lives with the agent, meaning the agent can spend autonomously. Convenient for some scenarios; an unacceptable risk for others.
• It's TON only — there is no cross-chain.

TONNode differs along three axes:

	Official @ton/mcp	TONNode
Key model	Custodial (split-key, signs on its own)	Non-custodial (returns unsigned TonConnect messages)
Cross-chain	No, TON only	TON → 6 EVM chains, atomic HTLC
Deployment	Local / HTTP / serverless	Local (npx) and a hosted endpoint

Non-custodial isn't a checkbox — it's an architectural moat. The server never signs and never holds funds or private keys. Even generate_wallet (which creates a new v3r2 / v4 / v5r1 / highload_v3 TON wallet) hands the mnemonic and keys to the user — the server doesn't store them. For a full comparison of the two approaches, see custodial vs non-custodial MCP.

One small naming note to avoid confusion: GRAM is the renamed Toncoin (the rename happened in June 2026); the network itself is still called TON.

How to connect and build your own DeFAI agent

You can start free and local — no card, no signup. The @tonnode/mcp package is open source (MIT) and speaks TON's native ADNL protocol with no HTTP middlemen.

Local and hosted config

Local config (public tool set, full read access) — just add it to your MCP client config:

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

Hosted endpoint (guaranteed throughput, your own key):

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

The config works with any MCP client: Claude, Cursor, ChatGPT/Codex.

A DeFAI agent skeleton

A DeFAI agent skeleton built on TONNode tools — the typical "enter a position on another chain" flow:

Check what the user holds:
  get_balance          → GRAM balance
  get_jetton_info      → jetton decimals (USDT = 6, usually 9)
  get_jetton_balance   → USDT/jetton balance (wallet derived on-chain)

If the user wants a swap inside TON:
  get_swap_quote → build_swap_tx → sign in the wallet

If the user wants to move value out to Base/Ethereum/…:
  get_crosschain_quote
  → build_crosschain_swap_tx (sign; the secret stays with the user)
  → track_crosschain_swap (wait until ready)
  → disclose_crosschain_secret (settlement)
  → build_crosschain_refund (if it stalls)

From here, everything hangs on the system prompt — the client routes the calls itself:

You are a DeFAI assistant for TON. Rules:
1. Before showing any jetton amount, call get_jetton_info (decimals)
   and get_jetton_balance.
2. For swaps: get_swap_quote first, show the rate, then build_swap_tx.
   Never ask for private keys — the transaction is signed by the
   user's wallet via TonConnect.
3. For cross-chain: get_crosschain_quote → build_crosschain_swap_tx →
   track_crosschain_swap → disclose_crosschain_secret.
   The source is always TON; the target is one of 6 EVM chains
   (Ethereum, Arbitrum, Base, BNB Chain, Polygon, Avalanche);
   TRON is not supported.
4. If a trade stalls, offer build_crosschain_refund.

We walk through building a trading agent step by step in a separate post — how to build a TON trading agent.

Pricing

Every plan includes all 16 tools — you only pay for throughput:

• Hobby — free forever, 60 requests/min
• Pro — $29/mo, 300 requests/min
• Scale — $199/mo, 1200 requests/min

The free Hobby key is issued right after sign-in, no card required. You can pay for Pro/Scale in GRAM or USDT on TON via TonConnect, or in BTC/ETH/SOL and more through an xRocket invoice in Telegram; the key is issued automatically once the payment settles.

---

A read-only MCP makes your agent an observer. Non-custodial swaps and cross-chain make it an executor — without taking the user's keys away. Plenty of tools can read TON; moving value from TON into six EVM chains without surrendering keys is, for now, TONNode alone. That's DeFAI on TON: the agent moves the value, and the owner keeps control.

Grab your free Hobby key and connect your first agent right now → tonnode.io/dashboard?plan=hobby

More on the topic: the full tool list at tonnode.io/mcp, limits and pricing at tonnode.io/pricing.