TONNODE
← 全部文章
6 分钟阅读

TON MCP 完整指南：如何让 AI 智能体接入 TON

TON MCP 服务器完整指南：什么是 MCP、AI 智能体为什么需要接入 TON、如何用 npx 免费接入或使用 hosted 密钥，以及 TONNode 全部 16 个工具速览。

TONMCPAI 智能体TONNode区块链开发非托管

你手上有一个 AI 智能体——Cursor 里的 Claude、跑在 Codex 上的脚本、自己写的定制 bot——你希望它能真正操作 TON：转账前查钱包余额、读交易历史、算 swap 报价、准备跨链兑换。可智能体再聪明也是“瞎”的：它在区块链里没有眼睛。常规做法是教它通过 HTTP 去调 toncenter 或 tonapi.io。痛苦随之而来：没有 key 时限额大约每秒一个请求，一有负载就收到 HTTP 429 Too Many Requests，全局配置里的公共 lite server 动不动回 not ready 或直接 ADNL 超时掉线，而且它们根本不存深度历史。一个本该“顺手查个余额”的智能体，栽在了基础设施上。

解决方案不是手把手教智能体调 API，而是给它一个 TON 的 MCP 服务器。下面是完整指南：什么是 MCP、智能体为什么需要它、如何一条命令免费接入，以及 TONNode 的 16 个工具都能干什么。

什么是 MCP，AI 智能体为什么需要它

MCP（Model Context Protocol）是一个开放标准，AI 智能体通过它调用外部工具。Claude、Cursor、ChatGPT/Codex 以及任何其他 MCP 客户端都支持它：你声明一组工具，智能体看到工具描述，自己决定调用哪个、传什么参数。

打个简单的比方：MCP 之于智能体，就像 USB 接口之于电脑。模型本身既没有网络访问权限，也接触不到区块链。但接上一个 MCP 服务器，智能体就有了一排“插座”：读余额、组装交易、跟踪一笔兑换。你说“钱包 X 上有多少 USDT”——模型明白需要 get_jetton_balance 这个工具，填入地址，拿回结构化的响应。

这与“直接给智能体一个 HTTP 端点”有本质区别。走裸 API 时，智能体必须在上下文里记住怎么构造请求、怎么解析响应、怎么转换地址和 raw 单位。这些全是幻觉的温床。MCP 把这套逻辑挪到服务器端：智能体看到的是签名清晰的 get_balance 工具，拿到的是现成的答案。错误更少、占用的上下文 token 更少、行为可预测。

TONNode（官网 tonnode.io）正是这样一个现成的 TON（The Open Network）hosted MCP 服务器。一个端点，16 个工具，覆盖读取、swap、跨链和钱包操作，直接跑在 TON 原生协议之上，中间没有任何 HTTP 转发层。

为什么智能体需要 TON 的 MCP 服务器，而不是公共 HTTP 网关

一个合理的疑问：既然有 toncenter、tonapi.io 这样的公共 API，为什么还要单独一个服务器？问题在于，公共网关适合偶尔手动查一下，但扛不住一个在循环里每分钟发几十个调用的智能体。

  • 限额和 429。没有 key 时，toncenter 和 tonapi.io 大约只给每秒一个请求，超了就返回 HTTP 429 Too Many Requests。智能体“读状态 → 做决策 → 再读一次”的循环瞬间撞上天花板——最终用户看到的不是答案，而是报错。
  • 公共 lite server 不可靠。全局配置里的 lite server（如果直接走 ADNL 访问 TON）是共享且限流的。有负载时它们会回 not ready、ADNL 超时掉线，而且不保存深度交易历史。
  • 裸响应 ≠ 给智能体的答案。即便 JSON 成功返回，往往也需要后处理：算出 jetton 钱包地址、按 decimals 换算 raw 单位、在不同地址格式之间转换。每一步交给模型来做，都是潜在的错误和多余的 token。

MCP 服务器把这些问题一并解决了：吞吐量绑定在你自己的 key 上、稳定可预期，计算放在服务器端完成，接口统一，返回的就是现成的结构化响应。顺带一提，如果你在群里看到“228 错误”——那是 TON 社区的梗数字，不是 API 状态码；真正的限流码就是 429。

关于免费路线的详细拆解，见另一篇：如何免费把 TON 接给智能体。

怎么接入：npx 免费方案与 hosted 密钥

有两条路，第一条完全免费。

方案一：npx 本地运行（免费，完整读取工具集）

完整的读取工具集无需注册、无需 key。@tonnode/mcp 包是开源的（MIT），发布在 npm 和 GitHub（tonnode/mcp）上，走 TON 原生 ADNL 协议。往 MCP 客户端配置里加上：

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

重启 Claude Desktop、Cursor 或其他客户端——工具会自动出现。各客户端的分步配置见指南：如何把 Claude 和 Cursor 接到 TON。

方案二：hosted 密钥（有保障的吞吐量）

当智能体跑上生产环境、请求量上来之后，就需要自己的 key 和稳定通道：

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

免费的 Hobby key 登录后立刻发放，不需要绑卡，而且 16 个工具全部可用——tonnode.io/dashboard?plan=hobby。

TONNode 的 16 个工具分组详解

所有套餐都能用全部工具——你付费买的只是吞吐量。下面按组拆解。

读取（8 个工具）

对任何只观察网络、不做任何写入的智能体来说，这组工具就是地基：

  • get_masterchain_info：主链的“链头”，也就是网络当前所处的位置。
  • get_balance：地址上的 GRAM 余额。
  • get_account_state：账户状态、标志位、最后一笔交易。
  • get_transactions：地址的交易历史。
  • run_get_method：调用合约的任意只读 get 方法。
  • get_jetton_balance：jetton 余额（比如 USDT）；jetton 钱包地址在链上现场计算，无需提前知道。
  • parse_address：地址转换与校验（EQ/UQ/raw），离线可用。
  • get_jetton_info：jetton 元数据——名称、符号、发行量，以及最关键的 decimals。decimals 对换算 raw 单位至关重要：USDT 是 6 位，绝大多数 jetton 是 9 位。

接入 TONNode 之后，给智能体的 prompt 可以这样写：

查一下钱包 UQ… 的 GRAM 和 USDT 余额，列出最近 5 笔交易。

智能体会自己调用 get_balance、get_jetton_balance（先通过 get_jetton_info 拿到 decimals），再调 get_transactions——全程没有一个手写的 HTTP 请求。

Swap（2 个工具）

TON 链内兑换，走 Omniston 协议，聚合 STON.fi 和 DeDust 的流动性：

  • get_swap_quote：针对 GRAM ⇄ jetton 交易对的 DEX 实盘报价。
  • build_swap_tx：未签名的 swap 交易，可直接交给 TonConnect 签名。

留意“未签名”这三个字——下面讲非托管时还会再提到它。

跨链（5 个工具）

TON 始终作为源链，兑换通过原子化的 HTLC escrow 完成——资金按秘密值的哈希锁定，只有两条链上的条件都满足才会解锁。支持：Ethereum、Arbitrum、Base、BNB Chain、Polygon、Avalanche。暂不支持 TRON。

  • get_crosschain_quote：跨链兑换报价。
  • build_crosschain_swap_tx：未签名的 HTLC escrow 交易，外加秘密值。
  • track_crosschain_swap：两条链上的交易阶段。
  • disclose_crosschain_secret：在链上确认就绪后披露秘密值，完成结算。
  • build_crosschain_refund：交易卡住时，从 escrow 中退回资金。

HTLC 机制保证兑换要么原子化完成，要么走 refund 原路退回——资金不会滞留在任何中间方手里。

钱包（1 个工具）

  • generate_wallet：创建新的 TON 钱包，支持 v3r2、v4、v5r1 或 highload_v3 版本，返回助记词、密钥和地址。服务器不保存生成的钱包——它会直接交到你手上。

工具的完整参数说明见 tonnode.io/mcp 页面。

非托管：为什么服务器永远碰不到你的私钥

这是最根本的区别，在让智能体接触真金白银之前，必须先把它弄明白。

swap、跨链和钱包生成这几组工具是严格非托管的。TONNode 服务器从不签名交易，也从不保管资金或私钥。智能体调用 build_swap_tx 或 build_crosschain_swap_tx 时，拿回的是一条未签名的 TonConnect 消息——一份交易草稿。签名的是用户的钱包，不是服务器。generate_wallet 生成的钱包同样直接交给你，不会留在服务器上。

打个比方：MCP 服务器是副驾上的领航员，负责规划路线、填好付款单。但按下“发送”、落笔签名的只能是你——握着自己钱包方向盘的人。哪怕智能体被攻破或者出了错，它也转不走资金——它手里只有未签名的草稿。

这里值得对比一下 TON Foundation 官方的 @ton/mcp。那是个很强的官方包：支持读取，发送 GRAM/jetton/NFT，通过 DEX 聚合器 swap，操作 NFT 和 DNS，创建和导入智能体钱包。但从架构上说，它是一个带 split-key 的托管型智能体钱包：operator 密钥由智能体自己持有并用来签名，owner 密钥在用户手里。而且它没有跨链——只有 TON。差异摆在明面上：官方包让智能体可以自主花钱、玩转 NFT/DNS；TONNode 则押注非托管、跨链和 hosted 方案。详细对比见 TONNode 对比官方 TON MCP 和托管与非托管 MCP 之争。

套餐与上手路线

所有套餐都包含全部 16 个工具——差别只在吞吐量：

套餐 价格 限额
Hobby 永久免费 60 请求/分钟
Pro $29/月 300 请求/分钟
Scale $199/月 1200 请求/分钟

Pro 和 Scale 可以用 TON 网络上的 GRAM 或 USDT 通过 TonConnect 支付，也可以用 BTC/ETH/SOL 等币种走 Telegram 里的 xRocket 账单支付。付款确认后 key 自动发放。（补充一句：GRAM 是 2026 年 6 月改名后的 Toncoin，网络本身仍然叫 TON。）

务实的上手路线：

  1. 领一个免费的 Hobby key——不用绑卡，登录即得，16 个工具全开：tonnode.io/dashboard?plan=hobby。
  2. 配好 hosted 配置（或者先用 npx -y @tonnode/mcp 在本地跑起来）。
  3. 给智能体发第一个读取类 prompt——余额、账户状态、交易历史——确认 429 和 not ready 再也不会来捣乱。

之后在生产环境撞到限额时，再看看套餐价格和工具总览。从免费 key 开始，几分钟就能把智能体接上 TON。

让你的智能体接入 TON

16 个 MCP 工具：读取、非托管兑换、跨链与钱包。免费档 60 次/分钟，无需银行卡。

领取免费密钥阅读文档

相关文章

6 分钟阅读

TON 非托管 Swap：AI 智能体如何不碰私钥兑换代币

AI 智能体如何在 TON 上完成非托管代币 Swap：通过 Omniston 调用 get_swap_quote 与 build_swap_tx，服务器不签名、不保管私钥，签名始终在用户钱包。

7 分钟阅读

如何以编程方式创建 TON 钱包（v4、v5、highload）

用 generate_wallet 一次调用以编程方式创建 TON 钱包：v3r2、v4、v5r1、highload 版本怎么选，助记词、密钥、地址，以及如何安全完成首笔入金。

7 分钟阅读

TON 到 Polygon 跨链兑换：原理与全流程解析

通过 MCP 完成 TON 到 Polygon 跨链兑换：原子化 HTLC 锁定如何在服务器从不保管私钥的前提下，非托管地把价值从 TON 转移到 Polygon。