무료 TON MCP: npx 또는 Hobby 플랜으로 AI 에이전트 연결

Claude나 Cursor에게 "이 TON 지갑 잔액을 확인하고 최근 트랜잭션을 보여줘"라고 시키면, 에이전트는 나름대로 성실하게 시도합니다. 글로벌 설정에 들어 있는 공개 라이트서버를 두드려 not ready를 받고, 재시도하다 ADNL 타임아웃에 걸립니다. 아니면 키 없이 toncenter로 가서 대략 초당 한 요청이라는 한도에 부딪히고 HTTP 429 Too Many Requests를 받습니다. 에이전트는 혼자서 TON을 읽지 못합니다. 도구가 필요합니다. 그리고 대부분의 개발자는 이 지점에서 노드를 직접 띄우고, 설정을 만지고, 접근 권한에 돈을 내야 한다고 생각합니다. 실제로는 그렇지 않습니다. 에이전트를 TON에 연결하는 일은 이런 삽질 없이 무료로 가능하며, 방법은 서로 다른 두 가지이고 둘 다 카드를 요구하지 않습니다.

에이전트에게 TON을 다룰 손을 쥐여주는 가장 빠른 방법은 MCP입니다. Model Context Protocol은 AI 에이전트(Claude, Cursor, ChatGPT/Codex를 비롯한 모든 MCP 클라이언트)가 외부 도구를 호출하는 방식을 정한 표준입니다. 에이전트에게 raw JSON-RPC를 두드리고 셀을 파싱하는 법을 가르치는 대신, get_balance나 get_jetton_balance 같은 완성된 도구 묶음을 건네주면 언제 호출할지는 에이전트가 알아서 판단합니다. TONNode는 TON 전용 hosted MCP 서버이며(사이트는 tonnode.io), 이를 통해 무료 TON MCP를 쓰는 길은 두 갈래인데 어느 쪽도 카드가 필요 없습니다. 둘 다 살펴보겠습니다.

무료 TON MCP: 로컬 npx와 Hobby 키, 두 가지 길

에이전트를 TON에 무료로 연결하려면 다음 중에서 고르면 됩니다.

1. npx를 이용한 로컬 실행 — 공개 설정만으로 동작하며, 키도 가입도 전혀 필요 없습니다. 패키지는 여러분의 머신에 내려받아져 실행됩니다.
2. 무료 Hobby 키 — 사이트에 로그인하면 키가 곧바로 발급되고, 카드는 필요 없으며, hosted 엔드포인트로 분당 60 요청을 쓸 수 있습니다.

둘의 차이는 도구 구성이 아니라, 프로세스가 어디서 돌고 처리량이 어디서 나오느냐에 있습니다. 가장 간단한 쪽부터 시작하겠습니다.

방법 1: 공개 설정으로 npx 로컬 실행 (키 없이)

말 그대로 MCP 클라이언트 설정 파일에 블록 하나를 넣으면 끝입니다. 사전 설치는 필요 없습니다. npx가 알아서 패키지를 가져옵니다.

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

이게 전부입니다. 클라이언트를 시작하면 로컬 프로세스 @tonnode/mcp가 뜨고, 네이티브 프로토콜로 TON에 접속해 에이전트에게 읽기 도구 전체를 넘겨줍니다. 키도, 카드도, 계정도 필요 없습니다.

내부 동작에서 중요한 부분이 하나 있습니다. @tonnode/mcp 패키지는 오픈소스(MIT)로 npm과 GitHub(tonnode/mcp)에 올라와 있고, 에이전트와 네트워크 사이에 HTTP 중간 계층 없이 TON 네이티브 ADNL 프로토콜로 동작합니다. 즉 남의 REST API를 감싸 놓고 결국 남의 rate limit에 걸리는 래퍼가 아니라, 네트워크에 직접 붙는 클라이언트입니다.

이 설정을 어디에 넣는가

• Claude Desktop / Claude Code — MCP 설정 파일의 mcpServers에 넣습니다.
• Cursor — 프로젝트별 MCP 서버 설정 또는 전역 설정에 넣습니다.
• ChatGPT/Codex를 비롯한 다른 MCP 클라이언트 — 각 클라이언트의 MCP 연결 섹션에 넣습니다.

클라이언트별 상세 설명과 화면 캡처는 별도 가이드에 정리해 두었습니다: Claude와 Cursor를 TON에 연결하는 법.

무료로 쓸 수 있는 것: TON 읽기 도구 전체

무료 로컬 모드는 기능을 잘라낸 데모가 아닙니다. 읽기 도구 전체, 즉 여덟 개의 도구가 열려 있고, 대다수 에이전트 작업에는 이것으로 충분합니다.

• get_masterchain_info — 마스터체인의 "헤드". 네트워크의 현재 상태이며, 에이전트는 이걸 보고 네트워크가 "지금 어디쯤 와 있는지"를 파악합니다.
• get_balance — GRAM 단위 지갑 잔액(GRAM은 2026년 6월에 이름이 바뀐 Toncoin이며, 네트워크 자체는 여전히 TON입니다).
• get_account_state — 계정 상태, 플래그, 마지막 트랜잭션. 컨트랙트가 배포됐는지, 지갑이 활성 상태인지 판단할 때 유용합니다.
• get_transactions — 주소별 트랜잭션 이력.
• run_get_method — 임의 컨트랙트의 read-only get 메서드를 호출합니다. 스마트 컨트랙트에 대한 만능 "무엇이든 읽기" 도구입니다.
• get_jetton_balance — USDT를 포함한 jetton 잔액. jetton 지갑 주소는 온체인에서 계산되므로 미리 알고 있을 필요가 없습니다.
• get_jetton_info — jetton 메타데이터: 이름, 심볼, 발행량, 그리고 계산에 결정적인 decimals. USDT는 decimals = 6, 대부분의 jetton은 = 9입니다. 이 숫자 없이는 raw 단위를 사람이 읽는 금액으로 환산할 수 없습니다.
• parse_address — 주소(EQ/UQ/raw) 변환 및 검증. 네트워크에 접속하지 않고 오프라인으로 동작합니다.

실전 예시를 하나 보겠습니다. "USDT 잔액을 호출 한 번으로 보여줘"라는 고전적인 작업은 get_jetton_info(decimals 확인) + get_jetton_balance 조합으로 해결됩니다. 에이전트에게는 사람 말로 된 프롬프트 하나면 충분합니다.

UQAbc...xyz 주소의 USDT 잔액을 확인하고
소수점 자릿수를 정확히 맞춰서 보여줘.

에이전트가 알아서 get_jetton_info를 호출해 decimals: 6을 확인하고, 이어서 get_jetton_balance를 부른 뒤 올바른 금액을 내놓습니다. 여러분이 작성한 코드는 한 줄도 없습니다. 자세한 설명은 TON용 MCP 가이드에, 별도 예제는 TON에서 USDT 잔액을 호출 한 번으로 확인하는 법에 있습니다.

방법 2: 무료 Hobby 키 — 카드 없이 분당 60 요청

로컬 npx는 개발과 일회성 작업에 좋지만 한계가 있습니다. TON 글로벌 설정에 들어 있는 공개 라이트서버를 거치기 때문입니다. 이 서버들은 공용이고 제한이 걸려 있어서, 부하가 걸리면 not ready나 ADNL 타임아웃을 자주 뱉고 깊은 이력도 보관하지 않습니다. 실제 사용자를 상대하는 프로덕션 에이전트에게 이건 복불복입니다.

여기서 두 번째 무료 경로, Hobby 플랜이 등장합니다. 영구 무료이고, 분당 60 요청을 제공하며, 키는 로그인 직후 카드 없이 바로 발급됩니다. 로컬 모드와의 차이는 요청이 여러분의 머신에서 공용 공개 인프라를 거쳐 나가는 게 아니라, 개인 키를 달고 TONNode의 hosted 엔드포인트를 통해 나간다는 점입니다. 즉 여러분에게만 묶인, 예측 가능한 분당 60 요청 한도가 생깁니다.

hosted 연결 설정은 다음과 같습니다.

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

로컬 설정과 다른 점은 두 가지입니다. 프로세스를 띄우는 대신 type: "http"를 쓴다는 것, 그리고 키 tn_live_…를 담은 Authorization 헤더가 붙는다는 것입니다. 에이전트 입장에서는 동작상의 차이를 전혀 느끼지 못합니다. 같은 도구, 같은 이름, 같은 파라미터입니다.

중요한 점이 있습니다. Hobby에서도 다른 모든 플랜과 마찬가지로 TONNode의 16개 도구 전부를 쓸 수 있습니다. 읽기뿐 아니라 스왑, 크로스체인, 지갑 생성까지요. 특히 hosted 키에서는 여덟 개의 읽기 도구에 generate_wallet이 더해집니다. v3r2, v4, v5r1, highload_v3 버전의 새 TON 지갑을 만드는 도구로, 니모닉과 키, 주소를 여러분에게 직접 돌려주며 서버는 생성된 지갑을 보관하지 않습니다. 플랜이 제한하는 것은 기능이 아니라 처리량입니다. 처리량이 필요해질 때만 그만큼 지불하면 됩니다.

Hobby 키 받기(카드 불필요): tonnode.io/dashboard?plan=hobby.

로컬이냐 hosted냐: 무료로 충분한 지점과 throughput이 필요한 지점

짧게 말하면, 개발과 프로토타입, 그리고 호출 빈도가 높지 않은 상황이라면 무료로 거의 항상 충분합니다. 두 모드의 차이는 도구 구성이 아니라 처리량에 있습니다.

모드	키 / 카드	처리량	용도
로컬 npx	둘 다 불필요	공개 라이트서버(공용, 제한 있음)	개발, 일회성 작업
Hobby (hosted)	키 필요, 카드 불필요	개인 키 기준 분당 60 요청	사이드 프로젝트, 가벼운 프로덕션
Pro / Scale (hosted)	키 + 결제	분당 300 / 1200 요청	부하가 큰 프로덕션

핵심 사실은 이것입니다. 모든 플랜에서 16개 도구를 전부 쓸 수 있습니다. 스왑과 크로스체인까지 포함해서요. 여러분이 돈을 내는 대상은 기능 "잠금 해제"가 아니라 오직 처리량입니다. Pro는 월 $29에 분당 300 요청, Scale은 월 $199에 분당 1200 요청입니다. 유료 throughput이 필요한 순간은 정확히, 분당 60 요청으로 부족해질 때 또는 실제 부하 상황에서 hosted 엔드포인트 mcp.tonnode.io에 예측 가능한 전용 한도가 필요할 때입니다. 전체 내역은 요금제 페이지와 도구 소개 페이지에 있습니다.

단계별: 에이전트를 연결하고 첫 호출 해보기

로컬 실행을 예로 삼아 전체 흐름을 정리해 보겠습니다(Hobby는 설정 블록만 다릅니다).

1단계. MCP 클라이언트 설정에 서버를 추가합니다. 위에서 본 npx -y @tonnode/mcp 블록을 가져와 여러분이 쓰는 클라이언트 설정에 붙여 넣습니다(Claude, Cursor, Codex — 경로는 클라이언트마다 다릅니다).

2단계. 클라이언트를 재시작합니다. @tonnode/mcp 프로세스가 뜨고 도구가 인식됩니다. 대부분의 클라이언트는 연결된 도구 목록을 화면에서 보여주니, ton이 나타났는지 확인하세요.

3단계. 에이전트에게 평범한 문장으로 작업을 시킵니다. 예를 들면 이렇습니다.

TON 마스터체인의 현재 헤드를 알아보고, 겸사겸사
UQAbc...xyz 주소의 GRAM 잔액도 확인해줘.

에이전트가 알아서 get_masterchain_info를 호출하고, 이어서 get_balance를 부른 뒤 결과를 사람 말로 돌려줍니다.

4단계. 조금 더 복잡한 작업도 프롬프트 하나면 됩니다. 이를테면 이렇습니다.

UQAbc...xyz 지갑에 USDT가 얼마나 있어? decimals를 반영한 금액으로 알려줘.

여기서 에이전트는 get_jetton_info를 호출해 USDT의 decimals(=6)를 확인하고, get_jetton_balance로 raw 잔액을 받은 뒤 사람이 읽는 금액으로 환산합니다. jetton 지갑은 온체인에서 직접 계산하므로 여러분이 그 주소를 넘겨줄 필요가 없습니다.

5단계. 공개 라이트서버의 한계에 부딪히면(not ready나 타임아웃이 보이기 시작하면) 해당 블록을 Hobby 키가 들어간 hosted 설정으로 교체하세요. 바뀌는 것은 설정뿐이고, 프롬프트와 에이전트 로직은 그대로입니다.

논커스터디얼: 무료 접근이 안전한 이유

당연한 질문이 하나 나옵니다. 서버가 무료인데 지갑도 만들어 주고 트랜잭션도 만들어 준다면, 내 키가 위험한 것 아닌가? 아닙니다. 그리고 이건 아키텍처의 원칙적인 입장입니다. TONNode는 철저히 논커스터디얼입니다.

서버는 어떤 것에도 서명하지 않고, 자금이나 개인 키를 보관하지도 않습니다. 읽기 도구는 공개된 온체인 상태를 읽을 뿐입니다. 그리고 상태를 바꾸는 도구, 즉 스왑과 크로스체인은 여러분 이름으로 아무것도 전송하지 않습니다. 서명되지 않은 TonConnect 메시지를 돌려줄 뿐입니다. 서명은 사용자 지갑이 로컬에서 자기 키로 합니다. generate_wallet(hosted 키에서 사용 가능)도 마찬가지입니다. 생성된 지갑과 니모닉은 여러분에게 전달되고, 서버는 그것을 자기 쪽에 남겨두지 않습니다.

다시 말해 무료 접근이 유료보다 조금이라도 더 위험할 이유가 없습니다. 트랜잭션에 서명할 수 있는 주체는 물리적으로 지갑 소유자뿐이고, 서버에는 무언가에 서명할 키 자체가 없습니다. 이것이 서버가 operator 키를 쥐고 직접 서명하는 커스터디얼 모델과의 근본적인 차이입니다. 두 접근 방식과 각각의 리스크는 커스터디얼 MCP와 논커스터디얼 MCP에서 따로 다뤘습니다.

정리

AI 에이전트에게 TON을 다룰 손을 쥐여주는 데 노드를 띄울 필요도, 카드를 꺼낼 필요도 없습니다. 로컬 npx -y @tonnode/mcp는 지금 당장 키 없이 읽기 도구 전체를 열어줍니다. 일단 써보기에 딱 좋습니다. 무료 Hobby 플랜은 공개 라이트서버가 버거워지기 시작할 때, 역시 카드 없이, 개인 키에 묶인 예측 가능한 분당 60 요청을 hosted 엔드포인트로 더해줍니다. 두 모드 모두 논커스터디얼이고, 같은 도구를 쓰며, 에이전트 로직을 한 줄도 고치지 않고 언제든 유료 throughput으로 넘어갈 수 있습니다.

무료 Hobby 키 받기(카드 불필요): tonnode.io/dashboard?plan=hobby