TON MCP: kết nối Claude và Cursor với TON từng bước

Ai từng thử bắt một AI agent làm gì đó trên TON đều biết bức tường này. Bạn nhờ Claude kiểm tra số dư ví — nó thành thật trả lời rằng mình không có quyền truy cập mạng, hoặc tệ hơn: bịa ra một địa chỉ jetton, nhầm nanoton với ton và bốc số từ trên trời. Đưa cho nó curl tới API công khai thì chỉ cần có tải là HTTP 429 Too Many Requests bay về, còn khi không có key thì giới hạn chỉ khoảng một request mỗi giây. Public liteserver trong global config lúc thì trả not ready, lúc thì rụng vì ADNL timeout. Vấn đề không nằm ở model — agent đơn giản là không có tay để chạm vào blockchain. Và MCP chính là thứ trao cho nó đôi tay ấy.

Dưới đây là cách kết nối Claude với TON chỉ trong vài phút, cùng với việc thiết lập Cursor TON MCP, Claude Code và Codex: config chính xác, cách chạy miễn phí qua npx và thời điểm chuyển sang key hosted khi bạn đụng trần giới hạn.

MCP là gì và tại sao agent cần nó để làm việc với TON

MCP (Model Context Protocol) là chuẩn mở để các AI agent gọi công cụ bên ngoài. Hãy hình dung cổng USB: trước đây mỗi thiết bị có một đầu cắm riêng, giờ chỉ cần một cổng cho tất cả. MCP cũng là "đầu cắm chung" như vậy giữa agent và thế giới bên ngoài. Claude Desktop, Claude Code, Cursor, ChatGPT/Codex và mọi MCP client khác đều nói cùng một ngôn ngữ: client kết nối tới MCP server, nhận danh sách công cụ và gọi chúng theo yêu cầu của model.

Để agent biết đường đi vào mạng TON, cần một MCP server làm được việc đó. Chúng ta sẽ dùng TONNode — MCP server hosted dành cho TON. Nó trao cho agent đúng 16 công cụ: đọc dữ liệu mạng (số dư, trạng thái account, giao dịch, get-method của contract, số dư và metadata của jetton), swap qua giao thức DEX Omniston, swap cross-chain bằng escrow HTLC nguyên tử và tạo ví. Các công cụ swap, cross-chain và ví hoàn toàn non-custodial: server không bao giờ ký giao dịch và không giữ khoá — nó trả về những message TonConnect chưa ký, còn việc ký là do ví của người dùng thực hiện.

Với hướng dẫn này, bốn công cụ read là đủ để kiểm tra kết nối:

• get_masterchain_info — đầu masterchain (cách nhanh nhất để chắc chắn server còn sống);
• get_balance — số dư GRAM theo địa chỉ;
• get_jetton_balance — số dư jetton (USDT và các loại khác), địa chỉ jetton wallet được tính on-chain;
• parse_address — chuyển đổi và kiểm tra địa chỉ EQ/UQ/raw, hoàn toàn offline.

Kết nối Claude với TON: khởi động nhanh qua npx (một câu lệnh)

Không cần cài đặt gì cả. Server local dựng lên bằng đúng một câu lệnh:

npx -y @tonnode/mcp

Package @tonnode/mcp là open source (MIT), nằm trên npm và GitHub (tonnode/mcp), chạy qua giao thức ADNL gốc của TON mà không có lớp HTTP trung gian nào. Config công khai cho bạn trọn bộ công cụ đọc miễn phí — đủ để agent đọc số dư, giao dịch, trạng thái account và gọi get-method.

Config cơ bản mà bạn sẽ dán vào các client trông như sau:

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

Hãy nhớ cấu trúc mcpServers — nó lặp lại gần như y hệt ở hầu hết mọi client. Phần còn lại tôi chỉ nói rõ nên đặt nó ở đâu. Phân tích chi tiết về chế độ miễn phí nằm trong bài riêng MCP cho TON miễn phí.

Không muốn cài local? Key Hobby miễn phí cho endpoint hosted được cấp ngay sau khi đăng nhập, không cần thẻ — lấy nó tại tonnode.io/dashboard rồi dán thẳng vào config bên dưới.

Claude Desktop: claude_desktop_config.json nằm ở đâu và điền gì vào đó

Claude Desktop đọc config MCP từ file claude_desktop_config.json. Đường dẫn phụ thuộc vào hệ điều hành:

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

Mở file (hoặc tạo mới nếu chưa có) và điền vào đúng object mcpServers đó:

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

Sau khi sửa xong, hãy khởi động lại ứng dụng — Claude Desktop chỉ nạp config lúc khởi động. Trong menu công cụ sẽ xuất hiện server ton. Bây giờ gõ vào chat:

Gọi get_masterchain_info và cho tôi xem seqno đầu masterchain.

Nếu agent trả về số block thì MCP đã được kết nối. Tương tự, bạn có thể nhờ "Kiểm tra số dư ví UQ…" — bên dưới get_balance sẽ chạy và trả về con số thật tính bằng GRAM (GRAM là tên mới của Toncoin từ tháng 6/2026; bản thân mạng lưới vẫn được gọi là TON).

Claude Code: lệnh claude mcp add và file .mcp.json

Trong Claude Code, server được thêm bằng một câu lệnh duy nhất từ terminal — nó tự ghi mọi thứ vào đúng file. Phương án local:

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

Dấu gạch ngang kép -- tách câu lệnh khởi động server khỏi các flag của chính claude. Sau đó Claude Code sẽ tạo (hoặc bổ sung) file .mcp.json của project. Nếu muốn, bạn có thể tự tay điền cùng object mcpServers đó vào file — kết quả y hệt:

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

Kiểm tra kết nối ngay trong CLI:

Dùng parse_address chuyển 0:83df... sang định dạng user-friendly EQ/UQ.

parse_address chạy offline, nên đây là bài test đáng tin cậy nhất: nó không phụ thuộc vào trạng thái mạng và cho thấy ngay lập tức rằng agent đã nhìn thấy các công cụ.

Cursor: file .cursor/mcp.json (theo project và toàn cục)

Tin vui cho những ai đã cấu hình xong Claude Desktop: Cursor dùng đúng cùng một định dạng mcpServers. Config copy nguyên xi — không cần viết lại gì cả. Khác biệt duy nhất là chỗ đặt file:

• .cursor/mcp.json ở thư mục gốc project — server chỉ nhìn thấy được trong project này;
• ~/.cursor/mcp.json — toàn cục, ở mọi project.

Khi có xung đột, file của project thắng. Ta đặt vào đó:

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

Đó chính là toàn bộ setup Cursor TON MCP: một file, bốn dòng payload thực sự. Sau khi lưu, kiểm tra trong Settings → MCP xem ton đã ở trạng thái Enabled chưa, rồi nhờ agent ngay trong editor:

Ví EQ... có bao nhiêu USDT? Gọi get_jetton_balance.

get_jetton_balance tự tính địa chỉ jetton wallet on-chain — bạn không cần tính tay. Về chuyện lấy số dư USDT chỉ bằng một lời gọi, có một bài phân tích riêng.

Codex CLI: config.toml và lệnh codex mcp add

Codex đứng riêng một góc: config của nó là TOML chứ không phải JSON, và nằm ở ~/.codex/config.toml. Cấu trúc khác, nhưng ý nghĩa vẫn thế. Ở local, cách đơn giản nhất để thêm server là dùng lệnh:

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

Trong file thì nó trông như thế này:

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

Với endpoint hosted, Codex chỉ cấu hình được qua config.toml — block đã dựng sẵn với url và header Authorization được trình bày ở phần về key hosted bên dưới. Nếu sửa TOML bằng tay, hãy nhớ rằng cú pháp ở đây không phải dấu ngoặc nhọn mà là các section trong ngoặc vuông, nên không thể copy máy móc JSON từ Cursor sang đây. Sau khi thêm xong, chạy codex rồi nhờ nó gọi get_masterchain_info — câu trả lời kèm seqno sẽ xác nhận kết nối đã thông.

Khi nào nên chuyển sang key hosted mcp.tonnode.io và cách gắn nó vào

Server npx local rất hợp để dùng thử và dựng prototype. Nhưng nó có trần: nó đi qua các public liteserver của TON lấy từ global config. Chúng là tài nguyên dùng chung và bị giới hạn — khi có tải thì thường trả not ready hoặc rơi vào ADNL timeout, và cũng không lưu lịch sử sâu. Ngay khi agent bắt đầu làm việc nghiêm túc — phục vụ người dùng, chạy vòng lặp polling số dư, gọi hàng chục get-method — bạn sẽ đụng đúng những giới hạn đó.

Sự khác biệt lộ rõ qua một tình huống đơn giản. Giả sử mỗi phút agent duyệt qua danh sách năm mươi ví và với mỗi ví gọi get_balance cộng get_jetton_balance — đã là khoảng một trăm lời gọi cho mỗi vòng. Trên config công khai, vòng lặp kiểu này gần như chắc chắn sẽ đụng trần khoảng một request mỗi giây: một phần địa chỉ trả về not ready, một phần rụng vì timeout, và agent buộc phải thử lại, càng làm nặng thêm cho liteserver dùng chung. Trên endpoint hosted với key riêng, cũng đúng một trăm lời gọi ấy nằm gọn trong băng thông đã cấp cho bạn, còn lịch sử và trạng thái account thì được trả về ổn định, không phải tranh giành tài nguyên chung.

Lúc đó là thời điểm chuyển sang endpoint hosted mcp.tonnode.io với key riêng và băng thông được đảm bảo. Key dạng tn_live_… chính là Bearer token tới https://mcp.tonnode.io/mcp. Config hosted khác ở phần transport: thay vì khởi chạy một process, ta khai báo HTTP và header xác thực:

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

Với Claude Code có sẵn lệnh — chú ý là các flag đứng trước tên server:

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

Với Codex, endpoint hosted được khai báo trong ~/.codex/config.toml — header xác thực nằm ở một section riêng:

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

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

Một điểm quan trọng về sự trung thực của bảng giá: cả 16 công cụ đều có mặt trên mọi gói, kể cả gói Hobby miễn phí. Key chỉ quyết định băng thông, chứ không quyết định bộ công cụ. Không có "tính năng premium khoá sau gói trả phí" nào cả — bạn trả tiền đúng cho lưu lượng request:

• 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.

Key Hobby miễn phí được cấp ngay sau khi đăng nhập vào dashboard, không cần thẻ. Nghĩa là việc chuyển từ chế độ local sang hosted không tốn một đồng nào, chừng nào 60 request mỗi phút vẫn còn đủ với bạn — và mức đó đã đáng tin cậy hơn hẳn public liteserver.

Phải làm gì nếu server không xuất hiện

Kết nối MCP hiếm khi hỏng theo kiểu phức tạp — gần như lúc nào cũng là một trong ba chuyện vặt sau:

• Server không có trong danh sách công cụ. Client chỉ đọc config lúc khởi động, nên sau khi sửa file hãy khởi động lại hoàn toàn Claude Desktop, Cursor, hoặc chạy lại session Codex. Trong Claude Code, kiểm tra trạng thái bằng lệnh claude mcp list.
• Server crash khi khởi động. Thường là do node/npx không nằm trong PATH — câu lệnh npx -y @tonnode/mcp chạy trong terminal thông thường phải khởi động được mà không báo lỗi. Nếu nó chạy được trong terminal nhưng không chạy từ client, hãy ghi đường dẫn tuyệt đối tới npx vào trường command trong config.
• Công cụ đọc trả về not ready hoặc timeout. Đây không phải lỗi setup của bạn, mà là public liteserver đang quá tải. Hãy thử lại request, hoặc nếu chuyện này lặp lại khi có tải, chuyển sang key hosted — ở đó là băng thông riêng thay vì hàng đợi dùng chung.

Ngoài ra hãy kiểm tra riêng tính hợp lệ của JSON và TOML: một dấu phẩy thừa trong mcpServers hay ngoặc bị lẫn lộn trong config.toml là nguyên nhân phổ biến nhất khiến client lặng lẽ bỏ qua server.

Thực hành nhanh: những công cụ bạn sẽ gọi đầu tiên

Bất kể dùng client nào, bài kiểm tra cuối cùng vẫn giống nhau — một lời gọi read đơn giản. Đây là những prompt điển hình và công cụ đứng sau chúng:

• "Seqno hiện tại của masterchain là bao nhiêu?" → get_masterchain_info. Đầu mạng lưới, cách tốt nhất để chắc chắn MCP nói chung còn sống.
• "Ví UQ… có bao nhiêu GRAM?" → get_balance. Số dư đồng coin gốc.
• "Địa chỉ này có bao nhiêu USDT?" → get_jetton_balance. Jetton wallet được tính on-chain, không cần biết trước địa chỉ của nó.
• "Chuyển địa chỉ EQ… sang định dạng UQ" → parse_address. Chuyển đổi và kiểm tra định dạng, hoàn toàn offline.

Tiếp theo thì có thể giao cho agent những việc thật sự:

• "Kiểm tra get_account_state theo địa chỉ và cho tôi biết contract đã deploy chưa, giao dịch gần nhất là khi nào."
• "Dùng run_get_method gọi get_wallet_data của jetton wallet rồi phân tích phản hồi." Cách gọi get-method read-only mà không cần cài SDK nằm trong bài gọi get-method không cần SDK.
• "Jetton này có bao nhiêu chữ số thập phân? Gọi get_jetton_info đi." (USDT có 6, phần lớn jetton khác có 9; decimals là thứ cần thiết để quy đổi đúng các đơn vị raw.)

Tổng quan chung về mọi khả năng của MCP cho TON được gom lại trong bài hướng dẫn lớn.

Kết luận

Kết nối agent với TON theo đúng nghĩa đen chỉ là bốn dòng JSON (hoặc một câu lệnh) trong config của client bạn dùng. npx -y @tonnode/mcp local chạy được mà không cần cài đặt, không cần key, với đầy đủ bộ công cụ đọc. Còn khi đụng trần giới hạn của public liteserver — bạn đổi transport sang endpoint hosted mcp.tonnode.io và gắn tn_live_… vào, không phải sửa một dòng nào trong logic của agent.

Hãy lấy key Hobby miễn phí và gắn nó vào config trong một phút → tonnode.io/dashboard?plan=hobby. Không cần thẻ, và toàn bộ 16 công cụ có sẵn ngay lập tức. Nếu muốn xem trước server làm được chính xác những gì, hãy ghé trang công cụ.