The tonnode/mcp server gives AI agents direct liteserver access to The Open Network (TON) blockchain via the native ADNL protocol (no HTTP gateways), enabling querying of on-chain data and execution of read-only contract methods.
get_masterchain_info: Retrieve the current masterchain head (workchain, shard, seqno, block hashes) to check network liveness and latest block height.
get_balance: Look up the native GRAM (Toncoin) balance of any TON address in both GRAM and nano units. Supports friendly (EQ…/UQ…) and raw (0:…) address formats.
get_account_state: Fetch full account state including status (active/frozen/uninit), balance, last transaction pointer, and code/data deployment flags.
get_transactions: Retrieve up to 30 recent transactions for an address (newest first), including logical time, Unix timestamp, incoming value, outgoing message count, and total fees.
run_get_method: Execute read-only smart contract get-methods (e.g., seqno, get_wallet_address) with optional integer arguments to inspect on-chain contract state.
Additional features include flexible deployment (embedded via npx, self-hosted, or hosted HTTP), configurable network access (mainnet by default, testnet or custom liteservers supported), and — when running as an HTTP server — API key authentication, rate limiting, session management, and health monitoring.
Provides direct liteserver access to The Open Network (TON) for querying blockchain state, balances, transactions, and running get-methods on smart contracts.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@tonnode/mcp get balance of EQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqB2N"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server that gives AI agents direct liteserver access to The Open Network (TON) — no HTTP gateways in the middle. Balances, account state, transaction history and contract get-methods over TON's native ADNL protocol.
Built by TONNode — private TON liteservers, archive nodes, mempool stream and indexed API.
Add to Claude Desktop, Claude Code, ChatGPT, Cursor, Codex or any MCP client:
{
"mcpServers": {
"ton": {
"command": "npx",
"args": ["-y", "@tonnode/mcp"]
}
}
}That's the whole integration. The server connects to TON mainnet via the public global config by default. Ready-made configs for every client — plus programmatic Node.js usage — live in examples/.
Related MCP server: Telegram MCP Server
Naming note: the native coin was renamed from Toncoin to GRAM in June 2026; the network itself is still called TON. Tool outputs use
*_gramfields.
Tool | What it does | Typical question |
| GRAM balance of an address | "How much GRAM does EQ… hold?" |
| Jetton/token balance (USDT and any TEP-74 token) | "How much USDT is on this wallet?" |
| Token metadata: name, symbol, decimals, supply | "What are this jetton's decimals?" |
| Recent transactions: values, senders, fees | "Did my payment arrive?" |
| Status, deployment flags, last-tx pointer | "Is this contract deployed?" |
| Read-only get-methods on contracts | "Call |
| Convert/validate EQ…/UQ…/raw forms, offline | "Are these two addresses the same?" |
| Masterchain head: seqno, shard, hashes | "Is the network (or my endpoint) alive?" |
| Firm DEX swap quote (GRAM ⇄ any jetton) via Omniston | "How much USDT for 100 GRAM right now?" |
| Unsigned, TonConnect-ready swap transaction | "Prepare that swap for my wallet to sign" |
| Quote TON → Ethereum/Arbitrum/Base/BNB/Polygon/Avalanche | "How much USDT on Ethereum for my TON USDT?" |
| Unsigned HTLC escrow transaction + its secret | "Start that cross-chain swap" |
| Live phases of a cross-chain trade on both chains | "Did the resolver lock my USDT on Ethereum?" |
| Reveal the secret — atomically settles both sides | "Complete the swap" |
| Unsigned cancellation that reclaims escrowed funds | "The trade stalled — get my money back" |
| Mint a fresh TON wallet (mnemonic + keys + address) | "Create a wallet for my agent to use" |
generate_wallet mints a brand-new wallet — a 24-word mnemonic, its ed25519 keypair and the address for the chosen contract version (v4 default, plus v3r2, v5r1 and highload_v3 for mass payouts). The v3r2/v4/v5r1 addresses come from @ton/ton's canonical contracts; highload_v3 is derived from the official contract code and cross-checked against a maintained reference implementation.
⚠️ This returns secret key material. In hosted mode the keys are generated on the server and returned over TLS — treat every generated wallet as hot: fine for programmatic/ephemeral use, but move any meaningful balance to cold storage, and keep the response out of logs and shared transcripts. The server never stores or logs the mnemonic or private key (only the public address). Operators can set
TONNODE_DISABLE_WALLET_GEN=1to remove the tool entirely.
get_swap_quote and build_swap_tx are powered by Omniston, STON.fi's RFQ protocol aggregating STON.fi and DeDust liquidity. No API key needed.
The flow is strictly non-custodial — the server never sees a private key, never signs and never broadcasts:
get_swap_quote locks a firm quote (amounts in raw indivisible units; the answer includes the slippage floor, price impact, gas budget and DEX route).
build_swap_tx turns the quote into unsigned messages in exactly the shape tonConnectUi.sendTransaction() expects — signing and sending stay with the wallet owner.
Quotes expire in about a minute, so build promptly. Omniston emulates the transfer while building: if the wallet doesn't hold the input amount, the build fails up front instead of burning gas on-chain.
The *_crosschain_* tools take the same idea across blockchains: pay in GRAM or any TON jetton, receive USDT/USDC/native coins on Ethereum, Arbitrum, Base, BNB, Polygon or Avalanche — settled through Omniston's atomic HTLC escrow, typically in well under a minute. TON is always the source chain (the signer is a TON wallet).
The agent drives the full atomic-swap lifecycle: quote → build (the tool generates the HTLC secret and hands it to the caller — the server keeps nothing) → sign & send → track both chains → disclose the secret to settle, or build a refund if the trade stalls. At no point can the server, the resolver or anyone else redirect the funds: the secret only completes the trade as quoted, and an unfilled escrow is always reclaimable by the owner wallet.
The package also ships a Streamable-HTTP entry for remote deployments (this is what powers mcp.tonnode.io):
TONNODE_KEYS=tn_live_abc,tn_live_def PORT=8808 npx -y @tonnode/mcp --httpWant a ready-made hosted endpoint instead of running your own? Keys for mcp.tonnode.io are issued at tonnode.io/mcp. Clients connect without installing anything:
{
"mcpServers": {
"ton": {
"url": "https://your-host/mcp",
"headers": { "Authorization": "Bearer tn_live_abc" }
}
}
}Requests are authenticated with Bearer keys and rate-limited per key (RATE_LIMIT_RPM, default 300). Besides Authorization: Bearer <key>, the server accepts a bare Authorization: <key> and X-API-Key: <key> — for gateways (e.g. Smithery) that reserve the Authorization header for themselves. Keys come from either TONNODE_KEYS (comma-separated, fixed) or TONNODE_KEYS_FILE — a JSON array of {"key", "label"?, "rpm"?, "expires"?} that is hot-reloaded on change and on SIGHUP: add or revoke customer keys with no restart, per-key rate limits, and self-expiring keys for subscription plans. A revoked key's live sessions are closed immediately. GLOBAL_RATE_LIMIT_RPM adds a total ceiling 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. Without keys the server refuses to start; set TONNODE_ALLOW_OPEN=1 to explicitly run keyless behind your own firewall. GET /healthz for monitoring, deploy/tonnode-keys.sh for key management.
The server binds 127.0.0.1 by default — put a TLS reverse proxy (Caddy, nginx) in front and set HOST=0.0.0.0 only if the proxy runs on another machine. Ready-made systemd + Caddy configs live in deploy/.
Env var | Meaning |
| Use your own liteservers instead of the public config: |
| Alternative global-config URL |
| Use the testnet config (or pass |
| HTTP mode: comma-separated Bearer API keys (simple, fixed) |
| HTTP mode: JSON key file with labels, per-key |
| HTTP mode: bind address (default |
| HTTP mode: listen port (default 8808) |
| HTTP mode: default requests per minute per key (default 300) |
| HTTP mode: total ceiling across all keys (default off) |
| HTTP mode: idle minutes before a session is swept (default 30) |
| HTTP mode: concurrent session caps (default 500 / 50) |
| Swap tools: alternative Omniston WebSocket endpoint (default |
| Swap tools: optional integrator revenue share in bps of the output — always visible to the caller as |
| Set to |
The default public-config liteservers are shared, rate-limited and keep no deep history — get_transactions beyond recent blocks will answer lt not in db. Agents also tend to query in bursts, which public gateways throttle.
For guaranteed throughput, archive depth and a node-level mempool stream, point TON_LITESERVERS at a private liteserver — provisioned in under a minute, payable in TON. How the config file, ADNL keys and archive routing work is covered in the TON Liteserver guide.
MIT © TONNode
Full account state: status (active/frozen/uninit), balance, last transaction pointer and whether code/data are deployed.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | TON address in friendly (EQ…/UQ…) or raw (0:…) form |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the returned fields and implies a read-only operation, but lacks details on error handling, permissions, or performance characteristics. Adequate for a simple query tool but not exceptional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the purpose and lists key details concisely. No extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately covers the main returned fields but lacks specifics on data types, formats (e.g., balance unit, pointer format), or edge cases. Sufficient for basic understanding but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the sole parameter 'address', so baseline is 3. The tool description does not add parameter-level information beyond what the schema already provides; it only describes output fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the full account state, listing specific fields (status, balance, last transaction pointer, code/data deployment). It distinguishes from siblings like get_balance (which likely returns only balance) and get_transactions (which returns transactions).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when needing comprehensive account information but does not explicitly state when to use this tool versus alternatives. No exclusion or prerequisite information is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Native GRAM balance of an address (GRAM is the renamed Toncoin), in both GRAM and nano units.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | TON address in friendly (EQ…/UQ…) or raw (0:…) form |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description adds value by noting the return includes both GRAM and nano units, but lacks disclosure of behavior like network calls, error handling, or idempotency. Basic but not insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence that is front-loaded with the tool's purpose. No extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool with one parameter and no output schema, the description is adequate but lacks detail on the response format. For a read operation, stating it returns a numeric balance in both units is helpful, but explicit mention of the data structure would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear parameter description. The description does not add additional meaning to the address parameter beyond what the schema already provides. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the native GRAM balance of an address, specifying the resource and units. It distinguishes from siblings like get_account_state (which may include balance but is more general) or get_transactions (different operation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. For example, get_account_state might also provide balance information, so explicit context on prioritizing this over others would help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Current TON masterchain head: workchain, shard, seqno and block hashes. Use to check network liveness and the latest block height.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It explains the output but does not explicitly state that the operation is read-only or disclose any behavioral nuances like side effects or freshness guarantees.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise, front-loaded sentences with no wasted words. Every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool, the description sufficiently explains what it does and why to use it. No missing critical information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is 100%. The description does not need to add parameter details; the baseline of 4 applies per rubric.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the current TON masterchain head with specific components (workchain, shard, seqno, block hashes) and distinguishes from sibling tools that deal with account states, balances, transactions, and methods.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states 'Use to check network liveness and the latest block height,' providing clear usage context. However, it lacks explicit when-not-to-use or alternative tool guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent transactions of an address (newest first): logical time, unix time, incoming value, outgoing message count and total fees.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many transactions to return (1–30) | |
| address | Yes | TON address in friendly (EQ…/UQ…) or raw (0:…) form |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses ordering (newest first) and field types, but 'recent' is vague (no time range). No mention of rate limits, permissions, or side effects, though it's a read operation. With no annotations, more detail would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence front-loads key info (recent, newest first, address). Every word adds value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lists return fields partially compensating for missing output schema, but lacks detail on time range, pagination, and error handling. With no annotations and siblings listed, more context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions (100% coverage). Description adds context about output fields but not directly about parameter meaning. Baseline 3 is appropriate as schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it returns recent transactions of an address, ordered newest first, and lists specific fields (logical time, unix time, incoming value, outgoing message count, total fees). Distinguishes from siblings like get_balance (just balance) or get_account_state (state info).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives like get_account_state or run_get_method. Does not specify prerequisites or scenarios where it is inappropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a read-only get-method on a smart contract (e.g. seqno, get_wallet_address). Integer arguments only in this version.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | Optional integer arguments, as decimal strings | |
| method | Yes | get-method name, e.g. "seqno" | |
| address | Yes | TON address in friendly (EQ…/UQ…) or raw (0:…) form |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only nature and integer-args limitation. No annotations provided, so description carries full burden. Could add error handling or response format, but sufficient for simple get-method.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with front-loaded purpose, zero redundancy. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple tool with 3 basic parameters and no output schema. Covers purpose, constraints, and examples. Could mention return value format or error cases, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover all three parameters (address, method, args). Description adds that args are 'integer decimal strings' and gives examples, enhancing beyond schema's 'decimal strings'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Execute' and resource 'read-only get-method on a smart contract' with specific examples (seqno, get_wallet_address). Distinguishes from sibling tools that likely query state or balance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for read-only operations and integer arguments, but no explicit when-to-use vs siblings or when-not-to-use. Context signals show sibling tools for different purposes, but description lacks direct guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.2get_account_stateget_balanceget_masterchain_infoget_transactionsrun_get_methodScored across 5 tools
Each tool targets a distinct aspect of the TON blockchain: account state, balance, masterchain info, transactions, and contract method execution. No two tools overlap in purpose.
Most tools follow a 'get_<noun>' pattern, but 'run_get_method' breaks the pattern with 'run' as the verb. Still, the naming is clear and readable.
With 5 tools, the set is well-scoped for a query-focused TON node server. Each tool serves a necessary function without redundancy.
The tools cover essential query operations for the TON blockchain, but missing features like detailed block information or contract code retrieval are minor gaps.
Provide AI agents and automation tools with contextual access to blockchain data including balance…
Wallet-signed Solana RPC for AI agents. No API keys, LLM-safe amounts, pay-per-call in SOL.
Gives AI agents a public IPv6 identity, hostname, port forwarding, web fetch, team mesh. Free tier.
S3 storage and Solana/Base/Ethereum health checks for AI agents, paid per call via x402.