Cómo conectar Claude y Cursor a TON: guía paso a paso

Cualquiera que haya intentado que un agente de IA haga algo con TON conoce este muro. Le pides a Claude que compruebe el saldo de una wallet y te responde, con toda honestidad, que no tiene acceso a la red — o peor: se inventa la dirección de un jetton, confunde nanotons con tons y saca las cifras de la nada. Le das un curl contra la API pública y bajo carga te llega un HTTP 429 Too Many Requests; sin clave, el límite ronda una petición por segundo. Los liteservers públicos del config global unas veces responden not ready y otras se caen por timeout de ADNL. El problema no es el modelo: el agente simplemente no tiene manos con las que tocar la blockchain. MCP le da exactamente esas manos.

A continuación, cómo conectar Claude a TON en unos minutos, y de paso configurar Cursor TON MCP, Claude Code y Codex: configs exactas, arranque gratuito con npx y el salto a una clave hosted cuando choques con los límites.

Qué es MCP y para qué lo necesita un agente que trabaja con TON

MCP (Model Context Protocol) es un estándar abierto con el que los agentes de IA invocan herramientas externas. Piensa en el USB: antes cada dispositivo tenía su propio conector; ahora hay un puerto para todo. MCP es ese mismo «conector universal» entre el agente y el mundo exterior. Claude Desktop, Claude Code, Cursor, ChatGPT/Codex y cualquier otro cliente MCP hablan el mismo idioma: el cliente se conecta a un servidor MCP, recibe la lista de herramientas y las llama cuando el modelo lo pide.

Para que el agente pueda hablar con la red TON hace falta un servidor MCP que sepa hacerlo. Vamos a usar TONNode, un servidor MCP hosted para TON. Le da al agente exactamente 16 herramientas: lectura de la red (saldo, estado de cuenta, transacciones, get-methods de contratos, saldos y metadatos de jettons), swaps vía el protocolo DEX Omniston, swaps cross-chain con escrow atómico HTLC y generación de wallets. Las herramientas de swap, cross-chain y wallet son estrictamente no custodiales: el servidor nunca firma transacciones ni guarda claves — devuelve mensajes TonConnect sin firmar que firma la wallet del usuario.

Para esta guía nos bastan cuatro herramientas de lectura con las que comprobar la conexión:

• get_masterchain_info — la cabeza de la masterchain (la forma más rápida de comprobar que el servidor está vivo);
• get_balance — saldo en GRAM de una dirección;
• get_jetton_balance — saldo de un jetton (USDT y otros); la jetton wallet se calcula on-chain;
• parse_address — conversión y validación de direcciones EQ/UQ/raw, totalmente offline.

Cómo conectar Claude a TON: arranque rápido con npx (un solo comando)

No hay que instalar nada. El servidor local se levanta con un comando:

npx -y @tonnode/mcp

El paquete @tonnode/mcp es open source (MIT), está en npm y GitHub (tonnode/mcp) y habla el protocolo nativo ADNL de TON sin capas HTTP intermedias. Con el config público tienes el set completo de herramientas de lectura gratis — suficiente para que el agente lea saldos, transacciones, estados de cuenta y llame a get-methods.

El config base que vas a pegar en los clientes es este:

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

Quédate con la estructura mcpServers: se repite casi idéntica en todos los clientes. A partir de aquí solo te muestro dónde colocarla. El análisis detallado del modo gratuito está en una guía aparte: MCP para TON gratis.

¿No quieres instalar nada en local? La clave gratuita Hobby para el endpoint hosted se entrega nada más iniciar sesión, sin tarjeta — consíguela en tonnode.io/dashboard y pégala directamente en el config de más abajo.

Claude Desktop: dónde está claude_desktop_config.json y qué escribir dentro

Claude Desktop lee la configuración MCP del archivo claude_desktop_config.json. La ruta depende del sistema:

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

Abre el archivo (o créalo si no existe) y escribe el mismo objeto mcpServers:

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

Tras editarlo, reinicia la aplicación: Claude Desktop solo carga el config al arrancar. En el menú de herramientas aparecerá el servidor ton. Ahora escribe en el chat:

Llama a get_masterchain_info y muéstrame el seqno de la cabeza de la masterchain.

Si el agente devuelve un número de bloque, MCP está conectado. También puedes pedirle «Comprueba el saldo de la wallet UQ…» — por debajo se ejecutará get_balance y devolverá una cifra real en GRAM (GRAM es el Toncoin renombrado en junio de 2026; la red en sí sigue llamándose TON).

Claude Code: el comando claude mcp add y el archivo .mcp.json

En Claude Code el servidor se añade con un solo comando desde la terminal — él mismo lo escribe todo en el archivo correcto. Variante local:

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

El doble guion -- separa el comando que arranca el servidor de los flags del propio claude. Después de esto, Claude Code crea (o completa) el .mcp.json del proyecto. Si prefieres, puedes escribir el mismo objeto mcpServers en el archivo a mano — el resultado es idéntico:

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

Verifica la conexión directamente en la CLI:

Con parse_address convierte 0:83df... al formato user-friendly EQ/UQ.

parse_address funciona offline, así que es el test más fiable: no depende del estado de la red y muestra al instante que el agente ve las herramientas.

Cursor: el archivo .cursor/mcp.json (por proyecto y global)

Buena noticia si ya configuraste Claude Desktop: Cursor usa exactamente el mismo formato mcpServers. El config se copia tal cual — no hay que reescribir nada. La única diferencia es dónde vive el archivo:

• .cursor/mcp.json en la raíz del proyecto — el servidor solo es visible en ese proyecto;
• ~/.cursor/mcp.json — global, en todos los proyectos.

En caso de conflicto gana el archivo del proyecto. Dentro ponemos:

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

Y ese es todo el setup de Cursor TON MCP: un archivo, cuatro líneas de carga útil. Tras guardar, comprueba en Settings → MCP que ton está en estado Enabled y pídele al agente, directamente en el editor:

¿Cuánto USDT hay en la wallet EQ...? Llama a get_jetton_balance.

get_jetton_balance calcula por sí solo la dirección de la jetton wallet on-chain — no hace falta calcularla a mano. Sobre cómo obtener el saldo de USDT con una sola llamada hay un artículo aparte.

Codex CLI: config.toml y el comando codex mcp add

Codex es un caso aparte: su configuración es TOML, no JSON, y vive en ~/.codex/config.toml. La estructura es distinta, pero la idea es la misma. En local, lo más fácil es añadir el servidor con el comando:

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

En el archivo queda así:

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

Para el endpoint hosted, Codex solo se configura vía config.toml — el bloque listo con url y la cabecera Authorization está en la sección sobre la clave hosted, más abajo. Si editas el TOML a mano, ten presente que aquí la sintaxis no son llaves sino secciones entre corchetes, así que no puedes copiar mecánicamente el JSON de Cursor. Después de añadirlo, arranca codex y pídele que llame a get_masterchain_info — una respuesta con el seqno confirmará la conexión.

Cuándo pasarse a la clave hosted de mcp.tonnode.io y cómo ponerla

El servidor local por npx es perfecto para probar y montar un prototipo. Pero tiene un techo: va a través de los liteservers públicos de TON del config global. Son compartidos y limitados — bajo carga responden not ready con frecuencia o se van por timeout de ADNL, y no guardan historial profundo. En cuanto el agente empieza a trabajar en serio — atiende usuarios, sondea saldos en bucle, dispara decenas de get-methods — chocas de frente con esos límites.

La diferencia se ve con un caso simple. Supón que el agente recorre cada minuto una lista de medio centenar de wallets y por cada una llama a get_balance más get_jetton_balance — eso ya es cerca de un centenar de llamadas por pasada. Con el config público, ese bucle chocará casi seguro con el límite de aproximadamente una petición por segundo: parte de las direcciones devolverá not ready, parte caerá por timeout, y el agente tendrá que reintentar, cargando aún más el liteserver compartido. En el endpoint hosted, con tu propia clave, ese mismo centenar de llamadas cabe en el throughput que tienes reservado, y el historial y los estados de cuenta llegan de forma estable, sin pelearte por un recurso común.

Entonces toca pasarse al endpoint hosted mcp.tonnode.io con tu propia clave y throughput garantizado. La clave con formato tn_live_… es un token Bearer para https://mcp.tonnode.io/mcp. El config hosted cambia el transporte: en lugar de lanzar un proceso, indicamos HTTP y la cabecera de autorización:

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

Para Claude Code hay un comando — fíjate en que los flags van antes del nombre del servidor:

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

Para Codex, el endpoint hosted se escribe en ~/.codex/config.toml — la cabecera de autorización va en una sección aparte:

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

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

Un punto importante sobre la honestidad de los planes: las 16 herramientas están disponibles en todos los planes, incluido el Hobby gratuito. La clave solo determina el throughput, no el set de herramientas. Nada de «funciones premium bajo suscripción» — pagas exactamente por el paso de peticiones:

• Hobby — gratis para siempre, 60 peticiones/min;
• Pro — $29/mes, 300 peticiones/min;
• Scale — $199/mes, 1200 peticiones/min.

La clave gratuita Hobby se entrega nada más entrar al dashboard, sin tarjeta. Es decir, pasar del modo local al hosted no cuesta ni un centavo mientras te basten 60 peticiones por minuto — y eso ya es notablemente más fiable que los liteservers públicos.

Qué hacer si el servidor no aparece

Una conexión MCP rara vez se rompe de forma complicada — casi siempre es uno de estos tres detalles:

• El servidor no aparece en la lista de herramientas. El cliente solo lee el config al arrancar, así que después de editar el archivo reinicia por completo Claude Desktop o Cursor, o reinicia la sesión de Codex. En Claude Code, comprueba el estado con claude mcp list.
• El servidor se cae al arrancar. Normalmente es que node/npx no está en el PATH — el comando npx -y @tonnode/mcp debería arrancar sin errores en una terminal normal. Si funciona en la terminal pero no desde el cliente, pon en el config la ruta absoluta a npx en el campo command.
• Las herramientas de lectura devuelven not ready o timeout. No es un error de tu setup, sino un liteserver público sobrecargado. Repite la petición o, si se repite bajo carga, pásate a la clave hosted — ahí tienes throughput dedicado en lugar de una cola compartida.

Revisa aparte que el JSON y el TOML sean válidos: una coma de más en mcpServers o unos corchetes mal puestos en config.toml son la causa más frecuente de que el cliente ignore el servidor en silencio.

Mini-práctica: las herramientas que llamarás primero

Sea cual sea el cliente, la comprobación final es la misma: una simple llamada de lectura. Estos son los prompts típicos y las herramientas detrás de cada uno:

• «¿Cuál es el seqno actual de la masterchain?» → get_masterchain_info. La cabeza de la red, la mejor forma de confirmar que MCP está vivo.
• «¿Cuánto GRAM hay en la wallet UQ…?» → get_balance. Saldo de la moneda nativa.
• «¿Cuánto USDT hay en esta dirección?» → get_jetton_balance. La jetton wallet se calcula on-chain; no necesitas conocer su dirección de antemano.
• «Convierte la dirección EQ… al formato UQ» → parse_address. Conversión y validación de formatos offline.

A partir de ahí ya puedes darle al agente tareas de verdad:

• «Comprueba get_account_state de esta dirección y dime si el contrato está desplegado y cuándo fue la última transacción.»
• «Con run_get_method llama a get_wallet_data en la jetton wallet y desglosa la respuesta.» Cómo disparar get-methods de solo lectura sin instalar un SDK se explica en el artículo sobre llamar a un get-method sin SDK.
• «¿Cuántos decimales tiene este jetton? Llama a get_jetton_info.» (USDT tiene 6; la mayoría de los jettons, 9; los decimals hacen falta para convertir bien las unidades raw.)

La visión de conjunto de todo lo que puede hacer MCP para TON está en la guía completa.

Conclusión

Conectar un agente a TON son literalmente cuatro líneas de JSON (o un comando) en el config de tu cliente. El npx -y @tonnode/mcp local arranca sin instalación y sin clave, con el set completo de lectura. Y cuando choques con los límites de los liteservers públicos, cambias el transporte al endpoint hosted mcp.tonnode.io y pones tu tn_live_…, sin tocar una sola línea de la lógica del agente.

Consigue la clave Hobby gratuita y pégala en el config en un minuto → tonnode.io/dashboard?plan=hobby. No hace falta tarjeta, y el set completo de 16 herramientas está disponible desde el primer momento. Si antes quieres ver exactamente qué sabe hacer el servidor, pásate por la página de herramientas.