Free TON MCP: Connect an AI Agent to TON via npx or Hobby

You ask Claude or Cursor to "check this TON wallet's balance and show the latest transactions" — and the agent genuinely tries. It hits a public liteserver from the global config, gets not ready, retries, and times out on ADNL. Or it goes to toncenter without a key, slams into the roughly one-request-per-second limit, and gets HTTP 429 Too Many Requests. An agent can't read TON on its own — it needs tools. And this is the point where most developers assume they'll have to run a node, wrestle with configs, and pay for access. In reality, you don't: there are two different ways to connect an agent to TON for free, and neither one asks for a credit card.

The fastest way to give an agent hands in TON is MCP. Model Context Protocol is the standard that lets AI agents (Claude, Cursor, ChatGPT/Codex, and any MCP client) call external tools. Instead of teaching your agent to poke raw JSON-RPC and parse cells, you hand it a set of ready-made tools like get_balance or get_jetton_balance — and it decides on its own when to call them. TONNode is a hosted MCP server for TON (see tonnode.io), and it gives you a free TON MCP in two different ways, neither of which requires a card. Let's walk through both.

Free TON MCP: two paths — local npx and a Hobby key

To connect an agent to TON for free, you have two options:

1. Local run via npx on the public config — no key, no signup at all. The package downloads and runs on your machine.
2. A free Hobby key — sign in on the site, the key is issued instantly, no card, 60 requests per minute through the hosted endpoint.

The difference between them isn't the toolset — it's where the process runs and where the throughput comes from. Let's start with the simplest one.

Option 1: local run via npx on the public config (no key)

This is literally one block in your MCP client's config. Nothing to install beforehand — npx pulls the package for you.

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

That's it. When the client starts, it spins up a local @tonnode/mcp process, connects to TON over the native protocol, and exposes the full set of read tools to the agent. No key needed, no card needed, no account needed.

One important detail under the hood: the @tonnode/mcp package is open source (MIT), lives on npm and GitHub (tonnode/mcp), and speaks TON's native ADNL protocol — no HTTP middlemen between your agent and the network. In other words, it's not a wrapper around someone's REST API that will eventually hit someone else's rate limit; it's a direct client to the network.

Where to put this config

• Claude Desktop / Claude Code — in the mcpServers section of the MCP configuration file.
• Cursor — in the project's MCP server settings, or globally.
• ChatGPT/Codex and other MCP clients — in their MCP connection section.

For a detailed walkthrough per client, with screenshots, see the dedicated guide: how to connect Claude and Cursor to TON.

What you get for free: the full TON read set

The free local mode isn't a stripped-down demo. You get the full read set — eight tools that cover the overwhelming majority of agent tasks:

• get_masterchain_info — the masterchain "head": the current network state the agent uses to figure out "where the network is right now."
• get_balance — wallet balance in GRAM (that's Toncoin, renamed in June 2026; the network itself is still called TON).
• get_account_state — account status, flags, last transaction. Handy for checking whether a contract is deployed and whether a wallet is active.
• get_transactions — transaction history for an address.
• run_get_method — call any read-only get method on any contract. Your universal "read anything" tool for smart contracts.
• get_jetton_balance — jetton balance, USDT included; the jetton wallet address is derived on-chain, so you don't need to know it in advance.
• get_jetton_info — jetton metadata: name, symbol, supply and — critical for any math — decimals. USDT has decimals = 6, most jettons have 9 — without that number you can't convert raw units into human-readable amounts.
• parse_address — address conversion and validation (EQ/UQ/raw), works offline, no network calls.

A practical example. The classic "show me the USDT balance in one shot" task comes down to chaining get_jetton_info (to learn the decimals) with get_jetton_balance. All the agent needs is a plain-language prompt:

Check the USDT balance at address UQAbc...xyz
and show it with the correct number of decimal places.

The agent calls get_jetton_info on its own, sees decimals: 6, then calls get_jetton_balance, and returns the correct amount — without a single line of your code. There's a full breakdown in the MCP for TON guide and a dedicated example of getting a USDT balance on TON in one call.

Option 2: the free Hobby key — 60 requests/min, no card

Local npx is great for development and one-off tasks, but it has a ceiling: it goes through the public liteservers from TON's global config. They are shared and rate-limited, frequently reply not ready or with an ADNL timeout under load, and don't keep deep history. For a production agent serving real users, that's a gamble.

This is where the second free path comes in — the Hobby plan. It's free forever, gives you 60 requests per minute, and the key is issued immediately after sign-in, no card required. The difference from local mode is that requests no longer go from your machine through shared public infrastructure — they go through TONNode's hosted endpoint with your personal key. That means a predictable 60 req/min limit that belongs to you and nobody else.

The hosted connection config looks like this:

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

There are exactly two differences from the local config: type: "http" instead of spawning a process, and an Authorization header with your tn_live_… key. The agent itself won't notice any difference — same tools, same names, same parameters.

Here's what matters: on Hobby, just like on every other plan, you get all 16 TONNode tools — not just reads, but swap, cross-chain, and wallet generation too. On the hosted key, the eight read tools are joined by others — notably generate_wallet, which creates a new TON wallet in version v3r2, v4, v5r1, or highload_v3: the tool returns the mnemonic, keys, and address directly to you, and the server does not store generated wallets. The plan limits throughput, not functionality. You only pay for throughput if you ever need more of it.

Get your Hobby key (no card): tonnode.io/dashboard?plan=hobby.

Local or hosted: where free is enough and where you need throughput

Short version: free covers you almost always, as long as we're talking development, prototypes, and a modest call rate. The difference between the modes is throughput, not toolset.

Mode	Key / card	Throughput	Best for
Local npx	Neither needed	Public liteservers (shared, limited)	Development, one-off tasks
Hobby (hosted)	Key, no card	60 requests/min on your own key	Side projects, light production
Pro / Scale (hosted)	Key + payment	300 / 1200 requests/min	Heavy production

The key fact: all 16 tools are available on every plan — swap and cross-chain included. You pay only for throughput, never to "unlock" features. Pro is $29/mo for 300 requests/min, Scale is $199/mo for 1200 requests/min. You need paid throughput precisely when 60 requests per minute stops being enough, or when you want a predictable, dedicated limit on the hosted mcp.tonnode.io endpoint under real load. The full breakdown is on the pricing page and the tools page.

Step by step: connect an agent and make the first call

Let's put it all together using the local setup as the example (for Hobby, only the config block changes).

Step 1. Add the server to your MCP client's config. Take the npx -y @tonnode/mcp block shown above and paste it into your client's config (Claude, Cursor, Codex — the path depends on the client).

Step 2. Restart the client. It spins up the @tonnode/mcp process and discovers the tools. Most clients show the list of connected tools in the UI — make sure ton is there.

Step 3. Give the agent a task in plain text. For example:

Get the current TON masterchain head, and while you're at it,
the balance of address UQAbc...xyz in GRAM.

The agent calls get_masterchain_info, then get_balance, and reports back in plain language.

Step 4. More complex tasks — still one prompt. Say:

How much USDT is in wallet UQAbc...xyz? Return the amount adjusted for decimals.

Here the agent calls get_jetton_info to learn USDT's decimals (=6), then get_jetton_balance to fetch the raw balance, and converts it into a human-readable amount. It derives the jetton wallet on-chain — you don't need to pass its address.

Step 5. When you hit the public liteserver ceiling (you'll see not ready or timeouts) — swap the block for the hosted config with a Hobby key. Only the config changes; your prompts and agent logic stay exactly the same.

Non-custodial by design: why free access is safe

A fair question: if the server is free, and it's the same server that generates wallets and builds transactions — am I risking my keys? No, and this is a deliberate architectural stance. TONNode is strictly non-custodial.

The server never signs anything and never holds funds or private keys. The read tools simply read public on-chain state. And the tools that do change state — swap and cross-chain — send nothing on your behalf: they return unsigned TonConnect messages. The user's wallet signs them, locally, with its own key. Same story with generate_wallet (available on the hosted key): the generated wallet and its mnemonic are handed to you, and the server keeps no copy.

In other words, free access is exactly as safe as paid access: only the wallet owner is physically able to sign transactions — the server has no keys to sign anything with. That's the fundamental difference from the custodial model, where the server holds an operator key and signs on its own. For a breakdown of the two approaches and their risks, see the piece on custodial vs non-custodial MCP.

Wrapping up

Giving an AI agent hands in TON requires neither running a node nor a credit card. A local npx -y @tonnode/mcp gets you the full read set with no key, right now — perfect for a first try. The free Hobby plan adds a predictable 60 requests/min on your own key through the hosted endpoint, also with no card, for when the public liteservers stop cutting it. Both modes are non-custodial, both use the same tools, and at any point you can move to paid throughput without rewriting a single line of your agent's logic.

Get a free Hobby key (no card): tonnode.io/dashboard?plan=hobby