TON MCP 연결법: Claude와 Cursor를 TON에 붙이는 단계별 가이드

AI 에이전트로 TON에서 뭔가 해보려 한 사람이라면 누구나 이 벽에 부딪혀 봤을 겁니다. Claude에게 지갑 잔액을 확인해 달라고 하면, 솔직하게 네트워크 접근 권한이 없다고 답하거나, 더 나쁜 경우에는 존재하지 않는 jetton 주소를 지어내고 nanoton과 TON을 헷갈리며 숫자를 근거 없이 내놓습니다. 공개 API를 직접 호출하는 curl을 쥐여주면 부하가 조금만 걸려도 HTTP 429 Too Many Requests가 날아오고, 키 없이 쓸 때의 한도는 대략 초당 한 요청 수준입니다. 글로벌 설정에 들어 있는 공개 라이트서버는 not ready를 뱉거나 ADNL 타임아웃으로 끊어지기 일쑤입니다. 문제는 모델이 아닙니다. 에이전트에게 블록체인을 직접 만질 손이 없을 뿐입니다. MCP가 바로 그 손을 쥐여줍니다.

아래에서는 몇 분 만에 Claude를 TON에 연결하고, 나아가 Cursor TON MCP, Claude Code, Codex까지 설정하는 방법을 다룹니다. 정확한 설정 파일, npx를 이용한 무료 실행, 그리고 한도에 부딪혔을 때 hosted 키로 넘어가는 과정까지 살펴봅니다.

MCP란 무엇이고, TON을 다루는 에이전트에게 왜 필요한가

MCP(Model Context Protocol)는 AI 에이전트가 외부 도구를 호출하는 방식을 정의한 개방형 표준입니다. USB를 떠올리면 이해가 쉽습니다. 예전에는 기기마다 전용 커넥터가 있었지만 이제는 포트 하나면 충분합니다. MCP는 에이전트와 바깥 세계 사이의 바로 그 "통합 커넥터"입니다. Claude Desktop, Claude Code, Cursor, ChatGPT/Codex를 비롯한 모든 MCP 클라이언트가 같은 언어를 씁니다. 클라이언트가 MCP 서버에 연결해 도구 목록을 받아오고, 모델의 요청에 따라 그 도구를 호출하는 식입니다.

에이전트가 TON 네트워크에 접근하려면 그 일을 할 줄 아는 MCP 서버가 필요합니다. 여기서는 TON 전용 hosted MCP 서버인 TONNode를 사용하겠습니다. 이 서버는 에이전트에게 정확히 16개의 도구를 제공합니다. 네트워크 읽기(잔액, 계정 상태, 트랜잭션, 컨트랙트 get 메서드, jetton 잔액과 메타데이터), DEX 프로토콜 Omniston을 통한 스왑, 원자적 HTLC 에스크로 기반 크로스체인 스왑, 그리고 지갑 생성입니다. 스왑, 크로스체인, 지갑 관련 도구는 철저히 논커스터디얼입니다. 서버는 트랜잭션에 절대 서명하지 않고 키도 보관하지 않습니다. 서명되지 않은 TonConnect 메시지를 돌려줄 뿐이고, 서명은 사용자 지갑이 합니다.

이 가이드에서 연결을 확인하는 데는 읽기 도구 네 개면 충분합니다.

• get_masterchain_info — 마스터체인의 헤드를 가져옵니다. 서버가 살아 있는지 확인하는 가장 빠른 방법입니다.
• get_balance — 주소의 GRAM 잔액을 조회합니다.
• get_jetton_balance — jetton 잔액(USDT 등)을 조회합니다. jetton 지갑 주소는 온체인에서 계산됩니다.
• parse_address — EQ/UQ/raw 주소를 변환하고 검증합니다. 완전히 오프라인으로 동작합니다.

Claude를 TON에 연결하는 법: npx 한 줄로 빠르게 시작하기

설치할 것은 없습니다. 로컬 서버는 명령 한 줄로 뜹니다.

npx -y @tonnode/mcp

@tonnode/mcp 패키지는 오픈소스(MIT)로 npm과 GitHub(tonnode/mcp)에 올라와 있고, 중간 HTTP 레이어 없이 TON 네이티브 ADNL 프로토콜로 동작합니다. 공개 설정만으로도 읽기 도구 전체를 무료로 쓸 수 있어서, 에이전트가 잔액과 트랜잭션, 계정 상태를 읽고 get 메서드를 호출하는 데는 부족함이 없습니다.

각 클라이언트에 붙여 넣게 될 기본 설정은 다음과 같습니다.

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

mcpServers 구조를 기억해 두세요. 거의 모든 클라이언트에서 토씨 하나 안 바꾸고 그대로 반복됩니다. 이제부터는 이 설정을 어디에 넣느냐만 짚어보겠습니다. 무료 모드에 대한 자세한 설명은 별도 가이드 TON용 MCP 무료로 쓰기에 정리해 두었습니다.

로컬 설치가 번거롭다면? hosted 엔드포인트용 무료 Hobby 키는 로그인 직후 카드 등록 없이 바로 발급됩니다 — tonnode.io/dashboard에서 받아 아래 설정에 그대로 넣으면 됩니다.

Claude Desktop: claude_desktop_config.json 위치와 작성 내용

Claude Desktop은 MCP 설정을 claude_desktop_config.json 파일에서 읽습니다. 경로는 운영체제마다 다릅니다.

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

파일을 열고(없으면 새로 만들고) 바로 그 mcpServers 객체를 넣습니다.

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

수정한 뒤에는 앱을 재시작하세요. Claude Desktop은 시작할 때만 설정을 읽어 들입니다. 도구 메뉴에 ton 서버가 나타날 겁니다. 이제 채팅에 이렇게 입력해 보세요.

get_masterchain_info를 호출해서 마스터체인 헤드의 seqno를 보여줘.

에이전트가 블록 번호를 돌려줬다면 MCP 연결이 된 겁니다. 같은 방식으로 "UQ… 지갑 잔액을 확인해 줘"라고 요청하면 내부적으로 get_balance가 실행되어 실제 GRAM 수치를 반환합니다(GRAM은 2026년 6월에 이름이 바뀐 Toncoin이며, 네트워크 자체는 여전히 TON입니다).

Claude Code: claude mcp add 명령과 .mcp.json 파일

Claude Code에서는 터미널 명령 하나로 서버를 추가할 수 있습니다. 필요한 파일에 알아서 기록해 줍니다. 로컬 방식은 이렇습니다.

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

이중 대시 --는 서버 실행 명령과 claude 자체의 플래그를 구분해 줍니다. 실행하면 Claude Code가 프로젝트의 .mcp.json을 생성하거나 기존 파일에 내용을 덧붙입니다. 원한다면 같은 mcpServers 객체를 직접 손으로 적어도 결과는 동일합니다.

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

연결은 CLI에서 바로 확인해 보세요.

parse_address로 0:83df...를 user-friendly EQ/UQ 형식으로 변환해줘.

parse_address는 오프라인으로 동작하기 때문에 가장 확실한 테스트입니다. 네트워크 상태와 무관하게 도구가 에이전트에게 보이는지를 즉시 알려줍니다.

Cursor: .cursor/mcp.json 파일 (프로젝트/전역)

Claude Desktop을 이미 설정한 분에게는 반가운 소식이 있습니다. Cursor는 완전히 동일한 mcpServers 형식을 씁니다. 설정을 그대로 복사해 오면 되고, 고쳐 쓸 부분은 없습니다. 차이는 파일 위치뿐입니다.

• 프로젝트 루트의 .cursor/mcp.json — 해당 프로젝트에서만 서버가 보입니다.
• ~/.cursor/mcp.json — 전역 설정으로, 모든 프로젝트에 적용됩니다.

둘이 충돌하면 프로젝트 파일이 우선합니다. 다음 내용을 넣습니다.

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

이것이 Cursor TON MCP 설정의 전부입니다. 파일 하나에 실질적인 내용은 네 줄입니다. 저장한 뒤 Settings → MCP에서 ton이 Enabled 상태인지 확인하고, 에디터에서 바로 에이전트에게 요청해 보세요.

EQ... 지갑에 USDT가 얼마나 있어? get_jetton_balance를 호출해줘.

get_jetton_balance는 jetton 지갑 주소를 온체인에서 직접 계산합니다. 손으로 구할 필요가 없습니다. USDT 잔액을 한 번의 호출로 가져오는 법은 별도 글에서 자세히 다뤘습니다.

Codex CLI: config.toml과 codex mcp add 명령

Codex는 조금 다릅니다. 설정 파일이 JSON이 아니라 TOML이고, 위치는 ~/.codex/config.toml입니다. 구조는 다르지만 의미는 같습니다. 로컬 서버는 명령으로 추가하는 게 가장 간편합니다.

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

파일에는 이렇게 들어갑니다.

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

hosted 엔드포인트의 경우 Codex는 config.toml을 통해서만 설정할 수 있습니다. url과 Authorization 헤더가 들어간 완성 블록은 아래 hosted 키 섹션에 있습니다. TOML을 직접 편집한다면 여기서는 중괄호가 아니라 대괄호 섹션 문법을 쓴다는 점을 기억하세요. Cursor의 JSON을 기계적으로 복사해 붙여 넣으면 안 됩니다. 추가한 뒤 codex를 실행하고 get_masterchain_info를 호출하게 해보세요. seqno가 담긴 응답이 오면 연결이 된 겁니다.

언제 mcp.tonnode.io hosted 키로 넘어가고, 어떻게 넣는가

로컬 npx 서버는 맛보기와 프로토타입 제작에는 더할 나위 없습니다. 다만 한계가 분명합니다. 글로벌 설정에 있는 TON 공개 라이트서버를 거치기 때문입니다. 이 서버들은 공용이고 한도가 걸려 있어서, 부하가 걸리면 자주 not ready를 반환하거나 ADNL 타임아웃에 걸리고, 오래된 히스토리도 보관하지 않습니다. 에이전트가 본격적으로 일하기 시작하면, 즉 실제 사용자를 상대하고 잔액 폴링을 루프로 돌리며 get 메서드를 수십 번씩 호출하게 되면 곧바로 이 한도에 부딪힙니다.

간단한 사례로 보면 차이가 뚜렷합니다. 에이전트가 1분에 한 번씩 지갑 50개 정도를 순회하면서 각각에 대해 get_balance와 get_jetton_balance를 호출한다고 해봅시다. 한 바퀴에 이미 약 100번의 호출입니다. 공개 설정에서는 이런 루프가 초당 한 요청 수준의 한도에 거의 확실히 걸립니다. 일부 주소는 not ready를 돌려주고, 일부는 타임아웃으로 실패하며, 에이전트는 재요청을 하면서 공용 라이트서버에 부하를 더 얹게 됩니다. 반면 전용 키를 쓰는 hosted 엔드포인트에서는 같은 100번의 호출이 할당된 처리량 안에 들어가고, 히스토리와 계정 상태도 공용 자원 쟁탈전 없이 안정적으로 반환됩니다.

이쯤 되면 직접 발급받은 키를 들고, 전용 처리량이 보장되는 hosted 엔드포인트 mcp.tonnode.io로 넘어갈 때입니다. tn_live_… 형식의 키는 https://mcp.tonnode.io/mcp에 대한 Bearer 토큰입니다. hosted 설정은 트랜스포트가 다릅니다. 프로세스를 실행하는 대신 HTTP와 인증 헤더를 지정합니다.

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

Claude Code에는 전용 명령이 있습니다. 플래그가 서버 이름 앞에 온다는 점에 유의하세요.

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

Codex에서는 hosted 엔드포인트를 ~/.codex/config.toml에 적습니다. 인증 헤더는 별도 섹션으로 지정합니다.

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

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

요금제에 관해 투명하게 짚고 갈 점이 하나 있습니다. 16개 도구 전부가 무료 Hobby를 포함한 모든 플랜에서 사용 가능합니다. 키는 도구 구성이 아니라 처리량만 결정합니다. "구독해야 풀리는 프리미엄 기능" 같은 건 없습니다. 딱 요청 처리량만큼만 지불하는 구조입니다.

• Hobby — 영구 무료, 분당 60 요청
• Pro — 월 $29, 분당 300 요청
• Scale — 월 $199, 분당 1200 요청

무료 Hobby 키는 대시보드에 로그인하면 카드 등록 없이 바로 발급됩니다. 즉 분당 60 요청으로 충분한 동안에는 로컬 모드에서 hosted로 넘어가는 데 한 푼도 들지 않습니다. 그것만으로도 공개 라이트서버보다 눈에 띄게 안정적입니다.

서버가 나타나지 않을 때 해야 할 일

MCP 연결이 복잡하게 깨지는 경우는 드뭅니다. 거의 항상 아래 세 가지 사소한 문제 중 하나입니다.

• 도구 목록에 서버가 보이지 않습니다. 클라이언트는 시작할 때만 설정을 읽으므로, 파일을 수정했다면 Claude Desktop이나 Cursor를 완전히 재시작하거나 Codex 세션을 다시 시작하세요. Claude Code에서는 claude mcp list 명령으로 상태를 확인할 수 있습니다.
• 서버가 시작할 때 죽습니다. 보통 node/npx가 PATH에 없는 경우입니다. 일반 터미널에서 npx -y @tonnode/mcp 명령이 에러 없이 시작되어야 합니다. 터미널에서는 되는데 클라이언트에서만 안 된다면, 설정의 command 필드에 npx의 절대 경로를 적어 주세요.
• 읽기 도구가 not ready나 타임아웃을 반환합니다. 설정이 잘못된 게 아니라 공개 라이트서버가 과부하 상태인 겁니다. 다시 요청해 보고, 부하가 걸릴 때마다 반복된다면 hosted 키로 넘어가세요. 공용 대기열 대신 전용 처리량을 쓰게 됩니다.

JSON과 TOML의 유효성도 따로 확인하세요. mcpServers에 쉼표를 하나 더 찍었거나 config.toml의 괄호가 꼬인 것이 클라이언트가 아무 말 없이 서버를 무시하는 가장 흔한 원인입니다.

미니 실습: 가장 먼저 호출하게 될 도구들

어떤 클라이언트를 쓰든 최종 확인 방법은 같습니다. 간단한 읽기 호출입니다. 대표적인 프롬프트와 그 뒤에서 동작하는 도구를 정리했습니다.

• "지금 마스터체인 seqno가 몇이야?" → get_masterchain_info. 네트워크의 헤드로, MCP가 살아 있는지 확인하는 최고의 방법입니다.
• "UQ… 지갑에 GRAM이 얼마나 있어?" → get_balance. 네이티브 코인 잔액입니다.
• "이 주소에 USDT가 얼마나 있어?" → get_jetton_balance. jetton 지갑은 온체인에서 계산되므로 주소를 미리 알 필요가 없습니다.
• "EQ… 주소를 UQ 형식으로 변환해 줘" → parse_address. 오프라인 변환 및 형식 검증입니다.

여기까지 됐다면 이제 에이전트에게 실전 과제를 줄 수 있습니다.

• "이 주소로 get_account_state를 확인해서 컨트랙트가 배포됐는지, 마지막 트랜잭션이 언제였는지 알려줘."
• "run_get_method로 jetton 지갑의 get_wallet_data를 호출하고 응답을 파싱해 줘." SDK 설치 없이 read-only get 메서드를 호출하는 방법은 SDK 없이 get 메서드 호출하기 글에서 다룹니다.
• "이 jetton의 소수점 자릿수가 몇이야? get_jetton_info를 호출해 줘." (USDT는 6, 대부분의 jetton은 9입니다. raw 단위를 제대로 환산하려면 decimals가 필요합니다.)

TON용 MCP의 전체 기능 개요는 종합 가이드에 모아두었습니다.

정리

에이전트를 TON에 연결하는 일은 말 그대로 클라이언트 설정에 JSON 네 줄(또는 명령 한 줄)을 넣는 것이 전부입니다. 로컬 npx -y @tonnode/mcp는 설치도 키도 없이 읽기 도구 전체와 함께 바로 뜹니다. 그리고 공개 라이트서버의 한도에 부딪히면, 에이전트 로직은 한 줄도 건드리지 않은 채 트랜스포트만 hosted 엔드포인트 mcp.tonnode.io로 바꾸고 tn_live_…를 넣어주면 됩니다.

무료 Hobby 키를 받아 1분 만에 설정에 넣어보세요 → tonnode.io/dashboard?plan=hobby. 카드는 필요 없고, 16개 도구 전체를 바로 쓸 수 있습니다. 서버가 정확히 무엇을 할 수 있는지 먼저 보고 싶다면 도구 페이지를 둘러보세요.