TON MCP: hướng dẫn đầy đủ cho AI agent truy cập TON

Bạn có một AI agent — Claude trong Cursor, một script chạy trên Codex, hay con bot tự viết — và bạn muốn nó thật sự làm việc được với TON: kiểm tra số dư ví trước khi gửi tiền, đọc lịch sử giao dịch, tính báo giá swap, dựng sẵn một giao dịch crosschain. Nhưng agent, dù thông minh đến đâu, vẫn mù: nó không có mắt trong blockchain. Cách làm thông thường là dạy nó tự gọi toncenter hoặc tonapi.io qua HTTP. Và đây là lúc rắc rối bắt đầu: không có key thì giới hạn chỉ khoảng một request mỗi giây, có tải là HTTP 429 Too Many Requests bay về, các public liteserver trong global config khi thì trả not ready, khi thì rớt vì ADNL timeout, còn lịch sử giao dịch sâu thì chúng đơn giản là không có. Con agent lẽ ra chỉ cần "xem hộ cái số dư" lại vấp ngã ngay ở tầng hạ tầng.

Lời giải không phải là dạy agent tự đi gọi API bằng tay, mà là trao cho nó một MCP server cho TON. Dưới đây là hướng dẫn đầy đủ: MCP là gì, agent cần nó để làm gì, cách kết nối miễn phí chỉ bằng một lệnh, và 16 tool của TONNode làm được những gì.

MCP là gì và AI agent cần nó để làm gì

MCP (Model Context Protocol) là một chuẩn mở để AI agent gọi các tool bên ngoài. Claude, Cursor, ChatGPT/Codex và mọi MCP client khác đều hiểu chuẩn này: bạn khai báo một bộ tool, agent nhìn thấy phần mô tả của chúng và tự quyết định gọi tool nào, với tham số gì.

Ví von cho dễ hình dung: MCP với agent giống như cổng USB với máy tính. Bản thân model không có quyền truy cập mạng, cũng chẳng có đường vào blockchain. Nhưng cắm một MCP server vào — agent lập tức có cả một dãy "ổ cắm": đọc số dư, dựng giao dịch, theo dõi một thương vụ. Bạn nói "ví X có bao nhiêu USDT" — model hiểu rằng nó cần tool get_jetton_balance, tự điền địa chỉ vào và nhận về một câu trả lời có cấu trúc.

Khác biệt so với kiểu "đưa cho agent một HTTP endpoint" là khác biệt về bản chất. Khi làm việc với API thô, agent phải giữ trong context cách dựng request, cách parse response, cách convert địa chỉ và đơn vị raw. Tất cả những chỗ đó đều là mảnh đất màu mỡ cho hallucination. MCP đẩy phần logic ấy về phía server: agent chỉ thấy một tool get_balance với signature rõ ràng và nhận về kết quả đã xử lý xong. Ít lỗi hơn, ít token trong context hơn, hành vi dự đoán được.

TONNode (website tonnode.io) chính là một MCP server hosted dựng sẵn cho TON (The Open Network). Một endpoint duy nhất, 16 tool cho đọc dữ liệu, swap, crosschain và làm việc với ví, chạy trên protocol gốc của TON mà không cần lớp HTTP trung gian.

Vì sao agent cần MCP server cho TON chứ không phải HTTP gateway công khai

Câu hỏi hợp lý: cần gì server riêng khi đã có các API công khai như toncenter và tonapi.io? Vấn đề là các gateway công khai chỉ hợp cho vài request thủ công lẻ tẻ, chứ không được thiết kế để chịu tải từ một agent quay vòng gọi hàng chục lần mỗi phút.

• Giới hạn và 429. Không có key, toncenter và tonapi.io cho khoảng một request mỗi giây, và khi vượt ngưỡng chúng trả HTTP 429 Too Many Requests. Agent chạy vòng lặp "đọc trạng thái → ra quyết định → đọc tiếp" đụng trần ngay lập tức — và thay vì câu trả lời, người dùng nhận về một lỗi.
• Public liteserver không đáng tin. Liteserver trong global config (nếu bạn đi thẳng vào TON qua ADNL) là dùng chung và bị giới hạn. Khi có tải, chúng trả not ready, rớt vì ADNL timeout, và cũng chẳng lưu lịch sử giao dịch sâu.
• Response thô ≠ câu trả lời cho agent. Ngay cả JSON trả về thành công cũng thường phải hậu xử lý: tính địa chỉ jetton wallet, quy đổi đơn vị raw theo decimals, convert địa chỉ giữa các định dạng. Mỗi bước như vậy nếu đẩy cho model đều là một lỗi tiềm tàng cộng thêm token thừa.

MCP server xử lý trọn gói tất cả: băng thông ổn định gắn với key của bạn, phần tính toán nằm ở server, và một interface thống nhất với câu trả lời đã được cấu trúc sẵn. Nhân tiện, nếu bạn gặp "lỗi 228" trong các nhóm chat — đó là con số meme của cộng đồng TON chứ không phải mã API; mã giới hạn thật sự chính là 429.

Bản phân tích chi tiết về hướng miễn phí nằm ở một bài riêng: cách kết nối TON với agent miễn phí.

Cách kết nối: miễn phí qua npx và key hosted

Có hai đường, và đường thứ nhất hoàn toàn miễn phí.

Cách 1. Chạy local qua npx (miễn phí, đủ bộ tool đọc)

Toàn bộ các tool đọc dữ liệu đều dùng được mà không cần đăng ký, không cần key. Package @tonnode/mcp là open source (MIT), nằm trên npm và GitHub (tonnode/mcp), chạy theo protocol ADNL gốc của TON. Thêm vào config của MCP client:

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

Khởi động lại Claude Desktop, Cursor hoặc client khác — các tool sẽ tự xuất hiện. Hướng dẫn cấu hình từng bước cho từng client nằm trong bài cách kết nối Claude và Cursor với TON.

Cách 2. Key hosted (băng thông được đảm bảo)

Khi agent đã chạy production và lượng request lớn, bạn cần key riêng cùng một kênh ổn định:

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

Key Hobby miễn phí được cấp ngay sau khi đăng nhập, không cần thẻ, và trên đó có sẵn cả 16 tool — tonnode.io/dashboard?plan=hobby.

16 tool của TONNode theo từng nhóm

Mọi gói cước đều có đủ tất cả các tool — bạn chỉ trả tiền cho băng thông. Cùng đi qua từng nhóm.

Đọc dữ liệu (8 tool)

Nền móng cho mọi agent chỉ quan sát mạng mà không thay đổi gì:

• get_masterchain_info — "cái đầu" của masterchain, điểm hiện tại của mạng.
• get_balance — số dư GRAM trên một địa chỉ.
• get_account_state — trạng thái account, các flag, giao dịch cuối cùng.
• get_transactions — lịch sử giao dịch của một địa chỉ.
• run_get_method — gọi bất kỳ get-method read-only nào của contract.
• get_jetton_balance — số dư jetton (ví dụ USDT); địa chỉ jetton wallet được tính on-chain, bạn không cần biết trước.
• parse_address — convert và kiểm tra địa chỉ (EQ/UQ/raw), chạy offline.
• get_jetton_info — metadata của jetton: tên, ký hiệu, tổng cung và quan trọng nhất là decimals. Decimals cực kỳ quan trọng khi quy đổi đơn vị raw: USDT có 6, còn phần lớn jetton có 9.

Ví dụ một prompt gửi cho agent đã cắm TONNode:

Kiểm tra số dư GRAM và USDT trên ví UQ…, cho tôi xem 5 giao dịch gần nhất.

Agent sẽ tự gọi get_balance, get_jetton_balance (sau khi lấy decimals qua get_jetton_info) và get_transactions — không cần một request HTTP thủ công nào.

Swap (2 tool)

Đổi token nội bộ trong TON qua protocol Omniston, nơi tổng hợp thanh khoản của STON.fi và DeDust:

• get_swap_quote — báo giá chắc chắn từ DEX cho cặp GRAM ⇄ jetton.
• build_swap_tx — giao dịch swap chưa ký, sẵn sàng để ký qua TonConnect.

Để ý chữ "chưa ký" — chúng ta sẽ quay lại nó ở phần nói về tính không lưu ký.

Crosschain (5 tool)

TON luôn đóng vai nguồn, còn việc trao đổi đi qua HTLC escrow nguyên tử — cơ chế mà tiền bị khóa theo hash của một secret và chỉ được mở khi các điều kiện ở cả hai mạng đều được thỏa mãn. Được hỗ trợ: Ethereum, Arbitrum, Base, BNB Chain, Polygon, Avalanche. TRON hiện chưa được hỗ trợ.

• get_crosschain_quote — báo giá cho giao dịch crosschain.
• build_crosschain_swap_tx — giao dịch HTLC escrow chưa ký, kèm secret.
• track_crosschain_swap — các pha của thương vụ trên cả hai mạng.
• disclose_crosschain_secret — công bố secret để thanh toán sau khi đã kiểm tra mức độ sẵn sàng on-chain.
• build_crosschain_refund — lấy lại tiền từ escrow nếu giao dịch bị treo.

Cơ chế HTLC nghĩa là giao dịch hoặc đi trọn vẹn theo kiểu nguyên tử, hoặc quay về qua refund — tiền không mắc kẹt ở một bên trung gian nào.

Ví (1 tool)

• generate_wallet — tạo ví TON mới thuộc phiên bản v3r2, v4, v5r1 hoặc highload_v3 và trả về mnemonic, khóa cùng địa chỉ. Ví vừa tạo thì server không lưu — nó được đưa thẳng cho bạn.

Tổng quan đầy đủ các tool kèm tham số nằm ở trang tonnode.io/mcp.

Không lưu ký: vì sao server không bao giờ giữ khóa của bạn

Đây là khác biệt mang tính nguyên tắc, và cần hiểu nó trước khi bạn để agent lại gần tiền của mình.

Các tool swap, crosschain và tạo ví đều không lưu ký một cách triệt để. Server TONNode không bao giờ ký giao dịch và không bao giờ giữ tiền hay khóa riêng. Khi agent gọi build_swap_tx hoặc build_crosschain_swap_tx, thứ nó nhận về là một message TonConnect chưa ký — một bản phôi giao dịch. Người ký là ví của người dùng, không phải server. Ví sinh ra từ generate_wallet cũng được đưa cho bạn và không nằm lại trên server.

Ví von: MCP server là hoa tiêu — vạch tuyến đường và điền sẵn tờ ủy nhiệm chi. Nhưng bấm "gửi" và đặt chữ ký lên đó thì chỉ mình bạn làm được, khi đang cầm lái chính chiếc ví của mình. Kể cả khi agent bị chiếm quyền hay làm sai, nó cũng không thể rút tiền đi đâu — trong tay nó chỉ có những bản phôi chưa ký.

Đến đây thì so sánh với @ton/mcp chính thức của TON Foundation là hữu ích. Đó là một package mạnh và chính danh: nó làm được đọc dữ liệu, gửi GRAM/jetton/NFT, swap qua DEX aggregator, làm việc với NFT và DNS, tạo và import ví-agent. Nhưng về mặt thiết kế nó là một ví-agent lưu ký theo cơ chế split-key: operator key do chính agent giữ và dùng để ký, còn owner key thuộc về người dùng. Và nó không có crosschain — chỉ TON thôi. Khác biệt ở đây rất sòng phẳng: package chính thức cho agent quyền tự chủ tiêu tiền và làm việc với NFT/DNS; còn TONNode đặt cược vào tính không lưu ký, crosschain và tùy chọn hosted. Phân tích chi tiết nằm ở các bài TONNode so với TON MCP chính thức và MCP lưu ký so với không lưu ký.

Gói cước và bắt đầu từ đâu

Mọi gói cước đều có đủ 16 tool — chỉ khác nhau ở băng thông:

Gói cước	Giá	Giới hạn
Hobby	miễn phí vĩnh viễn	60 request/phút
Pro	$29/tháng	300 request/phút
Scale	$199/tháng	1200 request/phút

Pro và Scale có thể thanh toán bằng GRAM hoặc USDT trên mạng TON qua TonConnect, hoặc bằng BTC/ETH/SOL và các đồng khác qua hóa đơn xRocket trong Telegram. Key được cấp tự động sau khi thanh toán được ghi nhận. (Nói thêm cho rõ: GRAM là Toncoin đã đổi tên hồi tháng 6/2026, còn bản thân mạng thì vẫn có tên là TON.)

Đường bắt đầu thực tế:

1. Lấy key Hobby miễn phí — không cần thẻ, có ngay sau khi đăng nhập, kèm đủ 16 tool: tonnode.io/dashboard?plan=hobby.
2. Ghi config hosted vào client (hoặc bắt đầu chạy local bằng npx -y @tonnode/mcp).
3. Đưa cho agent prompt đọc dữ liệu đầu tiên — số dư, trạng thái account, lịch sử — và tự thấy rằng 429 và not ready không còn cản đường nữa.

Sau đó, khi chạm trần giới hạn trên production, hãy xem bảng giá và tổng quan các tool. Bắt đầu bằng key miễn phí và cắm agent của bạn vào TON chỉ trong vài phút.