TON MCP 완벽 가이드: AI 에이전트에게 TON 접근 권한 주기

여러분에게 AI 에이전트가 있습니다. Cursor 안의 Claude일 수도, Codex로 짠 스크립트일 수도, 직접 만든 봇일 수도 있습니다. 그리고 이 에이전트가 TON에서 실제로 일하기를 바랍니다. 전송 전에 지갑 잔액을 확인하고, 트랜잭션 내역을 읽고, 스왑 견적을 계산하고, 크로스체인 교환을 준비하는 일 말입니다. 하지만 아무리 똑똑한 에이전트라도 눈이 없습니다. 블록체인 안을 들여다볼 눈이 없다는 뜻입니다. 흔한 접근은 toncenter나 tonapi.io를 HTTP로 직접 두드리도록 가르치는 것입니다. 그리고 바로 거기서 고통이 시작됩니다. 키 없이 쓰면 한도는 대략 초당 한 요청 수준이고, 부하가 걸리면 HTTP 429 Too Many Requests가 날아옵니다. 글로벌 설정에 들어 있는 공개 라이트서버는 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 도구를 보고 완성된 응답을 받습니다. 오류가 줄고, 컨텍스트에 실리는 토큰이 줄고, 동작이 예측 가능해집니다.

TONNode(사이트 tonnode.io)가 바로 TON(The Open Network)을 위한 완성된 hosted MCP 서버입니다. 엔드포인트 하나에 읽기, 스왑, 크로스체인, 지갑 작업을 아우르는 16개 도구가 들어 있으며, 중간 HTTP 계층 없이 TON 네이티브 프로토콜 위에서 동작합니다.

에이전트에게 공개 HTTP 게이트웨이가 아니라 TON용 MCP 서버가 필요한 이유

당연한 질문이 나옵니다. toncenter나 tonapi.io 같은 공개 API가 있는데 왜 별도의 서버가 필요할까요? 문제는 공개 게이트웨이가 일회성 수동 요청에는 쓸 만해도, 분당 수십 번씩 루프를 도는 에이전트의 부하를 감당하도록 설계되지 않았다는 데 있습니다.

• 한도와 429. 키 없이 쓰는 toncenter와 tonapi.io는 대략 초당 한 요청 수준을 허용하고, 초과하면 HTTP 429 Too Many Requests로 응답합니다. "상태를 읽고 → 판단하고 → 또 읽는" 루프를 도는 에이전트는 곧바로 천장에 부딪히고, 답 대신 사용자에게 오류를 내놓습니다.
• 공개 라이트서버는 믿을 수 없습니다. 글로벌 설정에 들어 있는 라이트서버(ADNL로 TON에 직접 접속하는 경우)는 공용이고 한도가 걸려 있습니다. 부하가 걸리면 not ready를 반환하고, ADNL 타임아웃으로 끊기며, 깊은 트랜잭션 히스토리를 보관하지 않습니다.
• 날것의 응답 ≠ 에이전트를 위한 응답. 성공한 JSON조차 후처리가 필요할 때가 많습니다. 제톤 지갑 주소를 계산하고, decimals에 맞춰 raw 단위를 환산하고, 주소를 포맷 간에 변환해야 합니다. 이런 단계를 모델에게 떠넘길 때마다 오류 가능성과 불필요한 토큰이 함께 쌓입니다.

MCP 서버는 이 문제를 한꺼번에 해결합니다. 여러분의 키에 묶인 안정적인 처리량, 서버 쪽에서 끝나는 계산, 그리고 구조화된 응답이 준비된 단일 인터페이스입니다. 참고로 채팅방에서 "228 오류"라는 말을 보게 되더라도, 그것은 TON 커뮤니티의 밈 숫자일 뿐 API 코드가 아닙니다. 실제 한도 코드는 바로 429입니다.

무료 경로에 대한 자세한 분석은 별도의 글에 있습니다: TON을 에이전트에 무료로 연결하는 방법.

연결 방법: npx로 무료로, 또는 hosted 키로

길은 두 갈래이고, 첫 번째는 완전히 무료입니다.

방법 1. npx로 로컬 실행 (무료, 읽기 도구 전체)

읽기 도구 전체 세트는 가입도 키도 없이 사용할 수 있습니다. @tonnode/mcp 패키지는 오픈소스(MIT)이며 npm과 GitHub(tonnode/mcp)에 올라와 있고, TON 네이티브 ADNL 프로토콜로 동작합니다. MCP 클라이언트 설정에 다음을 추가하십시오.

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

Claude Desktop, Cursor 또는 다른 클라이언트를 재시작하면 도구가 알아서 나타납니다. 클라이언트별 단계별 설정은 Claude와 Cursor를 TON에 연결하는 방법 가이드에 있습니다.

방법 2. hosted 키 (보장된 처리량)

에이전트가 프로덕션에서 돌고 요청이 많아지면, 자기 키와 안정적인 채널이 필요합니다.

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

무료 Hobby 키는 로그인 직후 카드 없이 발급되며, 이 키로 16개 도구를 전부 쓸 수 있습니다 — tonnode.io/dashboard?plan=hobby.

TONNode의 16개 도구, 그룹별로

모든 요금제에서 모든 도구를 쓸 수 있습니다. 여러분이 지불하는 것은 처리량뿐입니다. 그룹별로 살펴보겠습니다.

읽기 (8개 도구)

네트워크를 관찰하되 아무것도 바꾸지 않는 모든 에이전트의 토대입니다.

• get_masterchain_info — 마스터체인의 "머리", 즉 네트워크의 현재 지점.
• get_balance — 주소의 GRAM 잔액.
• get_account_state — 계정 상태, 플래그, 마지막 트랜잭션.
• get_transactions — 주소의 트랜잭션 내역.
• run_get_method — 컨트랙트의 모든 read-only get 메서드 호출.
• get_jetton_balance — 제톤 잔액(예: USDT). 제톤 지갑 주소는 온체인에서 계산되므로 미리 알고 있을 필요가 없습니다.
• parse_address — 주소 변환과 검증(EQ/UQ/raw). 오프라인으로 동작합니다.
• get_jetton_info — 제톤 메타데이터: 이름, 심볼, 발행량, 그리고 무엇보다 decimals. raw 단위를 환산하려면 decimals가 반드시 필요합니다. USDT는 6이고, 대부분의 제톤은 9입니다.

TONNode를 연결한 에이전트에게 줄 프롬프트 예시입니다.

지갑 UQ…의 GRAM과 USDT 잔액을 확인하고, 최근 트랜잭션 5건을 보여줘.

에이전트는 get_balance, get_jetton_balance(그 전에 get_jetton_info로 decimals를 가져온 뒤), get_transactions를 스스로 호출합니다. 수동 HTTP 요청은 단 한 번도 필요 없습니다.

스왑 (2개 도구)

STON.fi와 DeDust의 유동성을 집계하는 Omniston 프로토콜을 통한 TON 내부 교환입니다.

• get_swap_quote — GRAM ⇄ 제톤 페어에 대한 DEX 확정 견적.
• build_swap_tx — TonConnect로 서명할 준비가 된, 서명되지 않은 스왑 트랜잭션.

"서명되지 않은"이라는 표현에 주목하십시오. 이 표현은 논커스터디얼을 다루는 섹션에서 다시 짚겠습니다.

크로스체인 (5개 도구)

TON은 언제나 출발지 역할을 하고, 교환은 원자적 HTLC 에스크로를 통해 이뤄집니다. 시크릿의 해시로 자금이 잠기고, 양쪽 네트워크에서 조건이 충족될 때만 잠금이 풀리는 구조입니다. 지원 네트워크는 Ethereum, Arbitrum, Base, BNB Chain, Polygon, Avalanche입니다. TRON은 아직 지원되지 않습니다.

• get_crosschain_quote — 크로스체인 교환 견적.
• build_crosschain_swap_tx — 서명되지 않은 HTLC 에스크로 트랜잭션과 시크릿.
• track_crosschain_swap — 양쪽 네트워크에서의 거래 단계.
• disclose_crosschain_secret — 온체인 준비 상태를 확인한 뒤 정산을 위해 시크릿을 공개.
• build_crosschain_refund — 거래가 멈춰 버렸을 때 에스크로에서 자금을 회수.

HTLC 방식은 교환이 원자적으로 성사되거나 refund로 되돌아온다는 뜻입니다. 자금이 중개자에게 묶이는 일은 없습니다.

지갑 (1개 도구)

• generate_wallet — v3r2, v4, v5r1, highload_v3 버전의 새 TON 지갑을 생성하고 니모닉, 키, 주소를 반환합니다. 생성된 지갑을 서버는 보관하지 않습니다. 곧바로 여러분에게 전달됩니다.

파라미터를 포함한 전체 도구 개요는 tonnode.io/mcp 페이지에 있습니다.

논커스터디얼: 서버가 여러분의 키를 절대 쥐지 않는 이유

이것은 본질적인 차이이며, 에이전트를 돈 가까이에 두기 전에 반드시 이해해야 합니다.

스왑, 크로스체인, 지갑 생성 도구는 엄격하게 논커스터디얼입니다. TONNode 서버는 절대 트랜잭션에 서명하지 않고, 절대 자금이나 개인키를 보관하지 않습니다. 에이전트가 build_swap_tx나 build_crosschain_swap_tx를 호출하면 돌려받는 것은 서명되지 않은 TonConnect 메시지, 즉 트랜잭션 초안입니다. 서명은 서버가 아니라 사용자의 지갑이 합니다. generate_wallet으로 만든 지갑도 여러분에게 전달될 뿐 서버에는 남지 않습니다.

비유하자면 MCP 서버는 항로를 그리고 지급 전표를 채워 넣는 항해사입니다. 하지만 "보내기"를 누르고 서명을 얹는 일은 자기 지갑의 운전대를 쥔 여러분만 할 수 있습니다. 설령 에이전트가 탈취당하거나 실수를 하더라도 자금을 빼돌릴 수는 없습니다. 손에 쥔 것이 서명되지 않은 초안뿐이기 때문입니다.

여기서 TON Foundation의 공식 @ton/mcp와 비교해 보면 도움이 됩니다. 강력하고 공식적인 패키지입니다. 읽기, GRAM/제톤/NFT 전송, DEX 애그리게이터를 통한 스왑, 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은 TonConnect를 통해 TON 네트워크의 GRAM 또는 USDT로 결제할 수 있고, Telegram의 xRocket 인보이스를 통해 BTC/ETH/SOL 등 다른 화폐로도 결제할 수 있습니다. 결제가 처리되면 키는 자동으로 발급됩니다. (혹시 몰라 덧붙이면, GRAM은 2026년 6월에 이름이 바뀐 Toncoin이고, 네트워크 자체는 여전히 TON이라 불립니다.)

실용적인 시작 경로입니다.

1. 무료 Hobby 키를 받으십시오. 카드 없이, 로그인 직후, 16개 도구 전부와 함께 발급됩니다: tonnode.io/dashboard?plan=hobby.
2. hosted 설정을 적어 넣으십시오(또는 npx -y @tonnode/mcp로 로컬에서 시작하십시오).
3. 에이전트에게 읽기 프롬프트를 처음으로 던져 보십시오. 잔액, 계정 상태, 히스토리를 물어보고 429와 not ready가 더는 방해하지 않는지 확인하십시오.

그다음, 프로덕션에서 한도에 부딪히게 되면 요금제와 도구 개요를 살펴보십시오. 무료 키로 시작해서 몇 분 안에 에이전트를 TON에 연결하십시오.