TON MCP miễn phí: kết nối AI agent với TON qua npx

Bạn nhờ Claude hay Cursor "kiểm tra số dư của ví TON này và cho xem các giao dịch gần nhất" — và agent cũng thật lòng cố gắng. Nó gọi public liteserver từ global config, nhận về not ready, retry, rồi dính ADNL timeout. Hoặc nó đi thẳng tới toncenter mà không có key, đụng trần khoảng một request mỗi giây và nhận HTTP 429 Too Many Requests. Agent không tự đọc được TON — nó cần công cụ. Và đa số lập trình viên đến bước này đều nghĩ rằng phải dựng node, vọc config, trả tiền để có quyền truy cập. Thực tế thì không: bạn có thể kết nối agent với TON miễn phí và không vấp phải mấy cái ổ gà đó — bằng hai cách khác nhau, và cả hai đều không cần thẻ.

Cách nhanh nhất để trao cho agent đôi tay trong TON là MCP. Model Context Protocol là chuẩn để các AI agent (Claude, Cursor, ChatGPT/Codex và mọi MCP client) gọi công cụ bên ngoài. Thay vì dạy agent cách tự gọi JSON-RPC thô rồi bóc tách cell, bạn đưa cho nó một bộ công cụ dựng sẵn kiểu get_balance hay get_jetton_balance — còn khi nào gọi thì nó tự quyết. TONNode là MCP server hosted dành cho TON (website tonnode.io), và qua nó bạn có hai con đường để dùng TON MCP miễn phí, không con đường nào cần thẻ. Cùng xem cả hai.

TON MCP miễn phí: hai con đường — npx local và key Hobby

Để kết nối agent với TON miễn phí, bạn có hai lựa chọn:

1. Chạy local qua npx trên config công khai — hoàn toàn không cần key, không cần đăng ký. Package được tải về và chạy ngay trên máy bạn.
2. Key Hobby miễn phí — đăng nhập vào website, key được cấp ngay lập tức, không cần thẻ, 60 request mỗi phút qua endpoint hosted.

Khác biệt giữa chúng không nằm ở bộ công cụ, mà ở chỗ process chạy ở đâu và throughput đến từ đâu. Bắt đầu từ cách đơn giản nhất.

Cách 1: chạy local qua npx trên config công khai (không cần key)

Nó đúng nghĩa chỉ là một block trong config của MCP client. Không cần cài đặt trước gì cả — npx sẽ tự kéo package về.

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

Xong. Khi client khởi động, process local @tonnode/mcp sẽ được khởi chạy, kết nối vào TON qua giao thức gốc và trao cho agent trọn bộ công cụ đọc. Không cần key, không cần thẻ, không cần tài khoản.

Một chi tiết quan trọng ở bên dưới lớp vỏ: package @tonnode/mcp là open source (MIT), nằm trên npm và GitHub (tonnode/mcp), và chạy qua giao thức ADNL gốc của TON, không có lớp HTTP trung gian nào giữa agent của bạn và mạng. Nghĩa là nó không phải một lớp bọc quanh REST API của ai đó rồi đụng trần rate limit của người ta — đây là client kết nối thẳng vào mạng.

Đặt config này ở đâu

• Claude Desktop / Claude Code — vào mcpServers trong file cấu hình MCP.
• Cursor — trong phần cài đặt MCP server của project hoặc ở cấp global.
• ChatGPT/Codex và các MCP client khác — trong mục kết nối MCP của chúng.

Phân tích chi tiết cho từng client kèm ảnh minh hoạ nằm trong bài hướng dẫn riêng: cách kết nối Claude và Cursor với TON.

Miễn phí thì được gì: trọn bộ công cụ đọc TON

Chế độ miễn phí chạy local không phải bản demo bị cắt xén. Bạn có trọn bộ công cụ đọc, tám công cụ, đủ cho đại đa số tác vụ của agent:

• get_masterchain_info — "head" của masterchain: trạng thái hiện tại của mạng, để agent biết mạng "đang ở đâu".
• get_balance — số dư ví tính bằng GRAM (đây là Toncoin được đổi tên hồi tháng 6/2026; bản thân mạng vẫn gọi là TON).
• get_account_state — trạng thái account, các flag, giao dịch cuối cùng. Hữu ích để biết contract đã deploy chưa và ví còn hoạt động không.
• get_transactions — lịch sử giao dịch theo địa chỉ.
• run_get_method — gọi bất kỳ get-method read-only nào của contract tuỳ ý. Đây là công cụ "đọc mọi thứ" đa năng của bạn dành cho smart contract.
• get_jetton_balance — số dư jetton, bao gồm cả USDT; địa chỉ jetton wallet được tính on-chain, bạn không cần biết trước.
• get_jetton_info — metadata của jetton: tên, ký hiệu, tổng cung và — điều tối quan trọng khi tính toán — decimals. USDT có decimals = 6, đa số jetton là 9 — thiếu con số này bạn không thể quy đổi đơn vị thô thành số tiền dễ đọc.
• parse_address — chuyển đổi và kiểm tra địa chỉ (EQ/UQ/raw), chạy offline, không cần gọi mạng.

Ví dụ thực tế. Bài toán kinh điển "cho xem số dư USDT chỉ bằng một lệnh gọi" được giải bằng cặp get_jetton_info (để biết decimals) + get_jetton_balance. Agent chỉ cần một prompt bằng ngôn ngữ đời thường:

Kiểm tra số dư USDT tại địa chỉ UQAbc...xyz
và hiển thị nó với đúng số chữ số thập phân.

Agent sẽ tự gọi get_jetton_info, thấy decimals: 6, rồi gọi get_jetton_balance, và trả về con số chính xác — không cần một dòng code nào từ bạn. Phân tích kỹ hơn nằm trong hướng dẫn MCP cho TON và một ví dụ riêng, cách lấy số dư USDT trên TON chỉ bằng một lệnh gọi.

Cách 2: key Hobby miễn phí — 60 request/phút, không cần thẻ

npx chạy local rất hợp cho việc phát triển và những tác vụ lẻ, nhưng nó có giới hạn: nó đi qua các public liteserver trong global config của TON. Chúng dùng chung và bị giới hạn, thường trả not ready hoặc văng ADNL timeout khi tải cao, và không lưu lịch sử sâu. Với một agent chạy production phục vụ người dùng thật, đó là trò may rủi.

Đây là lúc con đường miễn phí thứ hai vào cuộc — gói Hobby. Nó miễn phí vĩnh viễn, cho 60 request mỗi phút, và key được cấp ngay sau khi đăng nhập, không cần thẻ. Khác biệt so với chế độ local là request không đi từ máy bạn qua hạ tầng công cộng dùng chung, mà qua endpoint hosted của TONNode với key riêng của bạn — nghĩa là bạn có một giới hạn ổn định 60 request/phút gắn riêng cho bạn.

Config cho kết nối hosted trông như sau:

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

So với config local có hai điểm khác: type: "http" thay cho việc khởi chạy một process, và header Authorization chứa key tn_live_… của bạn. Bản thân agent sẽ không nhận ra khác biệt nào khi làm việc — vẫn là những công cụ đó, vẫn tên đó, vẫn tham số đó.

Điều quan trọng: trên Hobby, cũng như trên mọi gói cước khác, bạn có toàn bộ 16 công cụ của TONNode — không chỉ đọc, mà cả swap, cross-chain, tạo ví. Chính trên key hosted, ngoài tám công cụ đọc bạn còn có thêm, đáng chú ý nhất là generate_wallet — tạo ví TON mới phiên bản v3r2, v4, v5r1 hoặc highload_v3: công cụ trả mnemonic, khoá và địa chỉ thẳng cho bạn, server không lưu lại những ví đã tạo. Gói cước giới hạn throughput chứ không giới hạn tính năng. Bạn chỉ trả tiền cho throughput, nếu bạn thực sự cần đến nó.

Lấy key Hobby (không cần thẻ): tonnode.io/dashboard?plan=hobby.

Local hay hosted: khi nào miễn phí là đủ, khi nào cần throughput

Ngắn gọn: bản miễn phí gần như luôn đủ, chừng nào câu chuyện còn là phát triển, prototype và tần suất gọi không cao. Khác biệt giữa hai chế độ không nằm ở bộ công cụ, mà ở throughput.

Chế độ	Key / thẻ	Throughput	Dùng cho
npx local	Không cần	Public liteserver (dùng chung, có giới hạn)	Phát triển, tác vụ lẻ
Hobby (hosted)	Cần key, không cần thẻ	60 request/phút trên key của bạn	Pet project, production nhẹ
Pro / Scale (hosted)	Key + thanh toán	300 / 1200 request/phút	Production tải cao

Điểm mấu chốt: mọi gói cước đều có đủ 16 công cụ — bao gồm cả swap và cross-chain. Bạn chỉ trả tiền cho throughput, chứ không phải để "mở khoá" tính năng. Pro có giá $29/tháng và cho 300 request/phút, Scale — $199/tháng và 1200 request/phút. Bạn chỉ cần đến throughput trả phí đúng vào lúc 60 request mỗi phút không còn đủ, hoặc khi bạn cần một giới hạn riêng ổn định trên endpoint hosted mcp.tonnode.io dưới tải thật. Bảng chi tiết đầy đủ nằm ở trang bảng giá và trang giới thiệu công cụ.

Từng bước: kết nối agent và thực hiện lệnh gọi đầu tiên

Ghép tất cả lại với ví dụ chạy local (với Hobby thì chỉ khác ở block config).

Bước 1. Thêm server vào config của MCP client. Lấy block npx -y @tonnode/mcp ở trên và dán vào config của client bạn dùng (Claude, Cursor, Codex — đường dẫn tuỳ theo client).

Bước 2. Khởi động lại client. Nó sẽ khởi chạy process @tonnode/mcp và nhận ra các công cụ. Ở đa số client, danh sách công cụ đã kết nối hiện ngay trên giao diện — hãy chắc chắn rằng ton đã xuất hiện.

Bước 3. Giao việc cho agent bằng văn bản thông thường. Ví dụ:

Lấy head hiện tại của masterchain TON và tiện thể
lấy luôn số dư của địa chỉ UQAbc...xyz tính bằng GRAM.

Agent sẽ tự gọi get_masterchain_info, rồi get_balance và trả kết quả bằng ngôn ngữ đời thường.

Bước 4. Những tác vụ phức tạp hơn — cũng chỉ một prompt. Chẳng hạn:

Ví UQAbc...xyz có bao nhiêu USDT? Trả về số tiền đã tính theo decimals.

Ở đây agent sẽ gọi get_jetton_info để biết decimals của USDT (=6), rồi gọi get_jetton_balance để lấy số dư thô, và quy đổi nó thành số tiền dễ đọc. Jetton wallet thì nó tự tính on-chain — bạn không cần truyền địa chỉ của nó.

Bước 5. Khi bạn đụng trần giới hạn của các public liteserver (thấy not ready hoặc timeout) — hãy thay block đó bằng config hosted với key Hobby. Chỉ có config thay đổi, còn prompt và logic của agent vẫn giữ nguyên.

Non-custodial: vì sao truy cập miễn phí vẫn an toàn

Câu hỏi hợp lý: nếu server đã miễn phí mà lại còn tự tạo ví và dựng giao dịch — liệu tôi có đang đánh cược với khoá của mình không? Không, và đây là một lựa chọn có tính nguyên tắc trong kiến trúc. TONNode hoàn toàn non-custodial.

Server không bao giờ ký giao dịch và không bao giờ giữ tiền hay khoá riêng tư. Các công cụ đọc chỉ đơn giản là đọc state công khai on-chain. Còn những công cụ làm thay đổi state — swap và cross-chain — không gửi bất cứ thứ gì thay mặt bạn: chúng trả về những message TonConnect chưa ký. Người ký chúng là ví của người dùng, ngay trên máy, bằng khoá của chính họ. generate_wallet cũng vậy (công cụ này có trên key hosted): ví được tạo cùng mnemonic của nó được trao thẳng cho bạn, server không giữ lại bản nào.

Nói cách khác, truy cập miễn phí không hề rủi ro hơn truy cập trả phí: về mặt vật lý chỉ chủ ví mới có thể ký giao dịch — server không có khoá để ký bất cứ thứ gì. Đây là khác biệt mang tính nguyên tắc so với mô hình custodial, nơi server giữ operator key và tự mình ký. Phân tích hai cách tiếp cận cùng rủi ro của chúng nằm trong bài riêng về MCP custodial và non-custodial.

Kết luận

Để trao cho AI agent đôi tay trong TON, bạn không cần dựng node và cũng không cần thẻ. npx -y @tonnode/mcp chạy local cho bạn trọn bộ công cụ đọc mà không cần key, ngay lúc này — hoàn hảo để dùng thử. Gói Hobby miễn phí bổ sung 60 request/phút ổn định trên key riêng của bạn qua endpoint hosted, cũng không cần thẻ, khi public liteserver bắt đầu không còn đủ. Cả hai chế độ đều non-custodial, cả hai đều dùng chung một bộ công cụ, và bất cứ lúc nào bạn cũng có thể chuyển sang throughput trả phí mà không phải viết lại gì trong logic của agent.

Lấy key Hobby miễn phí (không cần thẻ): tonnode.io/dashboard?plan=hobby