mcp

Purpose

TON MCP server provides AI agents with direct access to The Open Network (TON) liteserver, without an intermediate HTTP gateway. It enables Claude, ChatGPT, Cursor, Codex, and any MCP client to query on-chain data through TON's native ADNL protocol, including GRAM balances, account states, transaction history, and contract get-methods.

The server is built by TONNode, which also provides private TON liteservers, archive nodes, mempool streams, and a REST API (early access, available on request).

Main capabilities

• On-chain queries: Access liteserver through the native ADNL protocol to query GRAM balances, account states, transaction history, and contract get-methods. Supports private and archive endpoints.
• Wallet generation:generate_wallet The tool can generate a new wallet, including a 24-word mnemonic, an ed25519 key pair, and the address for the selected contract version (default v4, also supports v3r2、v5r1 and, for batch payments, highload_v3). v3r2/v4/v5r1 addresses come from @ton/ton standard contracts; highload_v3 is derived from official contract code and cross-checked against a maintained reference implementation.
• Swap:get_swap_quote and build_swap_tx are powered by Omniston, STON.fi's RFQ protocol, which aggregates liquidity from STON.fi and DeDust, with no API key required.
• Cross-chain swaps:*_crosschain_* The tool supports cross-chain payments and swaps, allowing payment with GRAM or any TON jetton and receipt of USDT/USDC/native coins on Ethereum, Arbitrum, Base, BNB, Polygon, or Avalanche, settled through Omniston's atomic HTLC escrow, usually within one minute. TON is always the source chain (the signer is a TON wallet).

Usage

Add to an MCP client: Can be added to Claude Desktop, Claude Code, ChatGPT, Cursor, Codex, or any MCP client. The server connects to TON mainnet by default through the public global configuration. Ready-made configuration for each client and Node.js programming usage are located in the examples/ directory.

Swap flow: Strictly non-custodial; the server never sees private keys, never signs, and never broadcasts.get_swap_quote Locks in a fixed quote (amounts are in raw indivisible units; the response includes the slippage floor, price impact, gas budget, and DEX route).build_swap_tx Converts the quote into tonConnectUi.sendTransaction() the unsigned message in the required shape—signing and sending are still done by the wallet owner. Quotes expire after about one minute, so they must be built promptly. Omniston simulates the transfer at build time: if the wallet does not hold the input amount, the build fails early instead of burning gas on-chain.

Cross-chain atomic swap lifecycle: quote → build (the tool generates the HTLC secret and gives it to the caller—the server retains nothing) → sign and send → track both chains → reveal the secret to settle, or build a refund if the transaction stalls.

Hosted/self-hosted HTTP mode: The package also includes a Streamable-HTTP entry point for remote deployment (i.e., the implementation behind mcp.tonnode.io). You can optionally use a ready-made hosted endpoint, with keys issued at tonnode.io/mcp, so clients can connect without installing anything. Requests are authenticated with a Bearer key and rate-limited per key (RATE_LIMIT_RPM, default 300). In addition to Authorization: Bearer <key> , the server also accepts bare Authorization: <key> and X-API-Key: <key>. Keys come from TONNODE_KEYS(comma-separated, fixed) or TONNODE_KEYS_FILE—a JSON array {"key", "label"?, "rpm"?, "expires"?}, hot-reloads on changes and SIGHUP: add or revoke customer keys, per-key rate limits, and subscription-plan self-expiring keys without a restart. Live sessions of revoked keys are closed immediately.GLOBAL_RATE_LIMIT_RPM Add a total cap across all keys to protect the backend liteserver. Sessions are private to the key that opened them, idle sessions are swept after SESSION_TTL_MIN(default 30 minutes), and concurrent sessions are capped per key and globally. The server refuses to start with no keys; set TONNODE_ALLOW_OPEN=1 to run explicitly keyless behind your own firewall.GET /healthz for monitoring,deploy/tonnode-keys.sh for key management. The server binds 127.0.0.1by default — put a TLS reverse proxy (Caddy, nginx) in front, and set HOST=0.0.0.0only if the proxy runs on another machine. Ready-made systemd + Caddy configs are in deploy/.

When to use it

• AI agents need to query TON on-chain data (balances, account states, transaction history, contract get-methods).
• Wallet generation for programmatic or ephemeral use cases.
• Agent-driven TON token swaps and cross-chain swaps.
• Scenarios that need a private liteserver or archival history to avoid public endpoint rate limits.

Limitations and caveats

• Wallet security:generate_wallet returns secret key material. In hosted mode keys are generated on the server and returned over TLS — every generated wallet should be treated as a hot wallet: suitable for programmatic/ephemeral use, but any meaningful balance should be moved to cold storage, and ensure responses do not appear in logs and shared records. The server never stores or logs mnemonics or private keys (only public addresses). Operators can fully remove this tool via TONNODE_DISABLE_WALLET_GEN=1 .
• Public liteserver: the default public-config liteserver is shared, rate-limited, and does not retain deep history —get_transactions beyond recent blocks will answer lt not in db. Agents also tend to burst queries, and public gateways rate-limit. For your own rate limits and archival history, point TON_LITESERVERS at a private liteserver — get a key pair and global.config.json from the console, and pay with a balance funded in GRAM or USDT.
• Mempool: pending messages are not exposed through this MCP server — none of the tools above read the mempool. TONNode offers the mempool as a separate WebSocket stream:wss://mempool.tonnode.io/v1/stream, one JSON object per external message, with filtering by destination wallet, op code, or DEX pool, and a brief replay after reconnection. Pricing is planned per single-key concurrent connections. Coverage is partial — a node only sees what reaches it through the overlay, with no guarantee of completeness or speed data — and messages sent through the TONNode liteserver usually do not appear in it (the node does not publish its own broadcasts; in a test on October 8, 2026, 2 of 20 sends appeared as copies relayed back by other nodes). Protocol, keys, and plans: tonnode.io/en/docs/mempool.

Naming note

The native token was renamed from Toncoin to GRAM in June 2026; the network itself is still called TON. Tool output uses the *_gram field.