Connect Claude and Cursor to TON: Step-by-Step MCP Setup

Anyone who has tried to get an AI agent to do anything with TON has run into the same wall. You ask Claude to check a wallet balance — it honestly replies that it has no network access, or worse: it makes up a jetton address, confuses nanotons with tons, and pulls numbers out of thin air. Give it curl against a public API and under load you get HTTP 429 Too Many Requests, while without a key the limit is roughly one request per second. The public liteservers from the global config either answer not ready or drop out on an ADNL timeout. The problem isn't the model — the agent simply has no hands to touch the blockchain with. MCP is exactly what gives it those hands.

Below is how to connect Claude to TON in a few minutes, plus how to set up Cursor TON MCP, Claude Code, and Codex: exact configs, a free start via npx, and the switch to a hosted key once you hit the limits.

What MCP is and why an agent needs it for TON

MCP (Model Context Protocol) is an open standard that lets AI agents call external tools. Think USB: every device used to have its own connector, now there's one port for everything. MCP is the same kind of universal plug between an agent and the outside world. Claude Desktop, Claude Code, Cursor, ChatGPT/Codex, and any other MCP client speak the same language: the client connects to an MCP server, gets a list of tools, and calls them whenever the model asks.

For the agent to reach the TON network, you need an MCP server that knows how. We'll use TONNode — a hosted MCP server for TON. It gives the agent exactly 16 tools: network reads (balance, account state, transactions, contract get-methods, jetton balances and metadata), swaps via the Omniston DEX protocol, cross-chain swaps over atomic HTLC escrow, and wallet generation. The swap, cross-chain, and wallet tools are strictly non-custodial: the server never signs transactions and never holds keys — it returns unsigned TonConnect messages that the user's wallet signs.

For this walkthrough, four read tools are all we need to verify the connection:

• get_masterchain_info — the masterchain head (the fastest way to confirm the server is alive);
• get_balance — GRAM balance for an address;
• get_jetton_balance — jetton balance (USDT and others), with the jetton wallet computed on-chain;
• parse_address — conversion and validation of EQ/UQ/raw addresses, fully offline.

How to connect Claude to TON: quick start via npx (one command)

Nothing to install. The local server spins up with a single command:

npx -y @tonnode/mcp

The @tonnode/mcp package is open source (MIT), lives on npm and GitHub (tonnode/mcp), and talks TON's native ADNL protocol with no HTTP middlemen. The public config gives you the full set of read tools for free — enough for the agent to read balances, transactions, account state, and hit get-methods.

The base config you'll be pasting into clients looks like this:

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

Remember the mcpServers structure — it repeats almost verbatim across every client. From here on, I'm just showing you where to put it. For a deep dive into the free mode, see the separate guide on free MCP for TON.

Don't want to run anything locally? A free Hobby key for the hosted endpoint is issued right after sign-in, no card required — grab it at tonnode.io/dashboard and drop it straight into the config below.

Claude Desktop: where claude_desktop_config.json lives and what to put in it

Claude Desktop reads its MCP config from claude_desktop_config.json. The path depends on your OS:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Open the file (or create it if it doesn't exist) and drop in that same mcpServers object:

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

After editing, restart the app — Claude Desktop only picks up the config on launch. The ton server will appear in the tools menu. Now type into the chat:

Call get_masterchain_info and show me the masterchain head seqno.

If the agent comes back with a block number, MCP is connected. You can also ask "Check the balance of wallet UQ…" — under the hood get_balance fires and returns a real figure in GRAM (GRAM is Toncoin, renamed in June 2026; the network itself is still called TON).

Claude Code: the claude mcp add command and .mcp.json

In Claude Code, you add the server with a single terminal command — it writes everything into the right file for you. The local variant:

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

The double dash -- separates the server launch command from claude's own flags. After this, Claude Code creates (or extends) the project-level .mcp.json. If you prefer, you can write the same mcpServers object into the file by hand — the result is identical:

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

Test the connection right in the CLI:

Use parse_address to convert 0:83df... to the user-friendly EQ/UQ format.

parse_address works offline, which makes it the most reliable test: it doesn't depend on network conditions and instantly proves the agent can see the tools.

Cursor: the .cursor/mcp.json file (per-project and global)

Good news if you've already set up Claude Desktop: Cursor uses the exact same mcpServers format. The config copies over one-to-one — nothing to rewrite. The only difference is where the file lives:

• .cursor/mcp.json in the project root — the server is visible in that project only;
• ~/.cursor/mcp.json — global, across all projects.

On conflict, the project file wins. Put this in:

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

That's the entire Cursor TON MCP setup: one file, four lines of payload. After saving, check Settings → MCP to confirm ton shows as Enabled, then ask the agent right in the editor:

How much USDT is on wallet EQ...? Call get_jetton_balance.

get_jetton_balance computes the jetton wallet address on-chain by itself — no manual derivation needed. There's a separate write-up on how to get a USDT balance in one call.

Codex CLI: config.toml and the codex mcp add command

Codex is the odd one out: its config is TOML, not JSON, and it lives in ~/.codex/config.toml. Different structure, same idea. The easiest way to add the server locally is the command:

codex mcp add ton -- npx -y @tonnode/mcp

In the file, it looks like this:

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

For the hosted endpoint, Codex is configured only through config.toml — the ready-made block with url and the Authorization header is shown in the hosted-key section below. If you're editing the TOML by hand, keep in mind the syntax here is square-bracket sections, not curly braces, so you can't mechanically paste JSON from Cursor into it. Once added, launch codex and ask it to call get_masterchain_info — a response with a seqno confirms the connection.

When to switch to a hosted mcp.tonnode.io key and how to plug it in

The local npx server is great for trying things out and building a prototype. But it has a ceiling: it goes through TON's public liteservers from the global config. They're shared and rate-limited — under load they often answer not ready or time out over ADNL, and they don't keep deep history. As soon as your agent starts working for real — serving users, polling balances in a loop, hitting dozens of get-methods — you slam into those limits.

The difference shows up in a simple scenario. Say the agent walks a list of fifty wallets once a minute, calling get_balance plus get_jetton_balance for each — that's already around a hundred calls per pass. On the public config, that loop is almost guaranteed to hit the roughly one-request-per-second limit: some addresses come back not ready, some time out, and the agent has to retry, piling even more load onto the shared liteserver. On the hosted endpoint with your own key, the same hundred calls fit comfortably within your dedicated throughput, and history and account state come back reliably — no racing for a shared resource.

That's when it's time for the hosted endpoint mcp.tonnode.io with your own key and guaranteed throughput. A key in the tn_live_… format is a Bearer token for https://mcp.tonnode.io/mcp. The hosted config differs only in transport: instead of launching a process, you point to HTTP and set an authorization header:

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

For Claude Code there's a command — note that the flags go before the server name:

claude mcp add --transport http ton https://mcp.tonnode.io/mcp \
  --header "Authorization: Bearer tn_live_…"

For Codex, the hosted endpoint goes into ~/.codex/config.toml — the authorization header lives in its own section:

[mcp_servers.ton]
url = "https://mcp.tonnode.io/mcp"

[mcp_servers.ton.headers]
Authorization = "Bearer tn_live_…"

One important note on pricing honesty: all 16 tools are available on every plan, including the free Hobby. The key determines only your throughput, not your tool set. No "premium features behind a subscription" — you pay purely for request 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 the moment you sign in to the dashboard, no card required. In other words, moving from local mode to hosted doesn't cost a cent as long as 60 requests per minute is enough for you — and that's already noticeably more reliable than the public liteservers.

What to do if the server doesn't show up

MCP setups rarely break in complicated ways — it's almost always one of three small things:

• The server isn't in the tools list. Clients read the config only at startup, so after editing the file, fully restart Claude Desktop or Cursor, or restart your Codex session. In Claude Code, check the status with claude mcp list.
• The server crashes on launch. Usually node/npx isn't in PATH — the command npx -y @tonnode/mcp should start cleanly in a regular terminal. If it works in the terminal but not from the client, put the absolute path to npx in the config's command field.
• Read tools return not ready or time out. That's not a problem with your setup — it's an overloaded public liteserver. Retry the request, or if it keeps happening under load, switch to a hosted key: dedicated throughput instead of a shared queue.

Separately, validate your JSON and TOML: a stray comma in mcpServers or mismatched brackets in config.toml is the most common reason a client silently ignores the server.

Mini-practice: the tools you'll call first

Whatever the client, the final check is the same — a simple read call. Here are the typical prompts and the tools behind them:

• "What's the current masterchain seqno?" → get_masterchain_info. The head of the network, the best way to confirm MCP is alive at all.
• "How much GRAM is on wallet UQ…?" → get_balance. Native coin balance.
• "How much USDT is on this address?" → get_jetton_balance. The jetton wallet is computed on-chain, no need to know its address in advance.
• "Convert address EQ… to the UQ format" → parse_address. Offline conversion and format validation.

From there you can give the agent real tasks:

• "Check get_account_state for this address and tell me whether the contract is deployed and when the last transaction was."
• "Call get_wallet_data on a jetton wallet via run_get_method and parse the response." How to hit read-only get-methods without installing an SDK is covered in the get-method without an SDK write-up.
• "How many decimals does this jetton have? Call get_jetton_info." (USDT has 6, most jettons have 9; you need decimals to convert raw units correctly.)

A full overview of everything MCP can do for TON lives in the big guide.

Wrapping up

Connecting an agent to TON is literally four lines of JSON (or one command) in your client's config. The local npx -y @tonnode/mcp runs with no install and no key, with the full read tool set. And when you hit the limits of the public liteservers, you flip the transport to the hosted endpoint mcp.tonnode.io and drop in your tn_live_… — without changing a single line of your agent's logic.

Grab a free Hobby key and plug it into your config in a minute → tonnode.io/dashboard?plan=hobby. No card needed, and the full set of 16 tools is available right away. Want to see exactly what the server can do first? Check the tools page.