MCP: give AI agents TON access

Model Context Protocol (MCP) is an open standard that lets AI agents call external tools over a simple JSON-RPC transport. An MCP server exposes typed tools; the agent (Claude Desktop, Claude Code, Cursor, ChatGPT/Codex, or anything else MCP-compatible) discovers them at startup and invokes them when a conversation needs live data. @tonnode/mcp is an MCP server that speaks the TON liteserver protocol, so your agent can read balances, account state, and transaction history, and execute get-methods against the chain — without you writing any glue code.

Quick start

The server runs from npm, no install step:

npx -y @tonnode/mcp

By default it starts in stdio mode, which is what local agent clients expect. Register it with your client:

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

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

Claude Code

claude mcp add tonnode -- npx -y @tonnode/mcp

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json in your project:

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

Codex

Add to ~/.codex/config.toml:

[mcp_servers.tonnode]
command = "npx"
args = ["-y", "@tonnode/mcp"]

Restart the client. The five tonnode tools appear in its tool list.

Point it at a private endpoint

Without configuration the server falls back to public-config liteservers, which are rate-limited to roughly 1 req/s and routinely return not ready or ADNL timeout 652 under load. For anything beyond a one-off query, set TON_LITESERVERS to your own endpoint. The value is a JSON array of liteserver entries — host, port, and base64 Ed25519 public key, exactly as shown in your TONNode dashboard:

{
  "mcpServers": {
    "tonnode": {
      "command": "npx",
      "args": ["-y", "@tonnode/mcp"],
      "env": {
        "TON_LITESERVERS": "[{\"ip\":\"<your-host>\",\"port\":41000,\"key\":\"<base64-key>\"}]"
      }
    }
  }
}

Claude Code equivalent:

claude mcp add --env TON_LITESERVERS='[{"ip":"<your-host>","port":41000,"key":"<base64-key>"}]' tonnode -- npx -y @tonnode/mcp

Codex equivalent:

[mcp_servers.tonnode]
command = "npx"
args = ["-y", "@tonnode/mcp"]

[mcp_servers.tonnode.env]
TON_LITESERVERS = '[{"ip":"<your-host>","port":41000,"key":"<base64-key>"}]'

Multiple entries in the array are load-balanced with failover. Any endpoint that accepts global-config-format liteserver credentials works here; TONNode plans start at 10 req/s guaranteed (see pricing).

Tools

Tool	What it does
get_masterchain_info	Current masterchain block: seqno, shard, root hash. The liveness check.
get_balance	Balance of an address, returned as balance_gram.
get_account_state	Full account state: status, code, data, last transaction id.
get_transactions	Transaction history for an address, paginated from a given lt/hash.
run_get_method	Execute a contract get-method (e.g. get_wallet_data, get_jetton_data) with arguments.

You don't call these by name — the agent picks them from natural language. Prompts that map cleanly onto the tools:

• "What does EQBx… hold?" → get_balance
• "Is EQBx… an active contract or uninitialized?" → get_account_state
• "Show the last 10 transactions of EQBx… and summarize the inbound transfers." → get_transactions
• "Call get_jetton_data on this jetton master and tell me the total supply." → run_get_method
• "What's the current masterchain seqno? Is my endpoint synced?" → get_masterchain_info

Balances are denominated in GRAM (the native coin of the TON network, renamed from Toncoin in June 2026).

Hosted mode

To serve MCP over HTTP — for remote agents, shared team access, or ChatGPT connectors — start with --http:

TONNODE_KEYS=key1,key2 \
PORT=8080 \
RATE_LIMIT_RPM=600 \
TON_LITESERVERS='[{"ip":"<your-host>","port":41000,"key":"<base64-key>"}]' \
npx -y @tonnode/mcp --http

• --http — switch from stdio to the streamable HTTP transport.
• TONNODE_KEYS — comma-separated API keys; requests must present one. Leave unset only on trusted networks.
• PORT — listen port.
• RATE_LIMIT_RPM — per-key request ceiling per minute.

Put it behind TLS (reverse proxy) before exposing it publicly. A hosted instance multiplexes many agents onto one liteserver plan, so size the plan's req/s to your aggregate agent traffic.

Archive depth

A standard liteserver holds recent state only. If the agent asks for deep history — "every transaction this wallet ever made", state at an old block — get_transactions will stop where the node's pruned history ends. For genesis-depth queries (TON genesis is May 2021), point TON_LITESERVERS at an archive endpoint instead; the config format is identical. Running your own archive node means 16–20 TB NVMe, 128 GB RAM, and 1–2 weeks of sync, which is why archive access is usually rented.

Questions or a config that won't connect: t.me/tonnode_support.