Guía TON MCP: cómo dar a tu agente de IA acceso a TON

Tienes un agente de IA — Claude en Cursor, un script montado sobre Codex, un bot a medida — y quieres que trabaje de verdad con TON: que compruebe el saldo de una wallet antes de enviar, lea el historial de transacciones, calcule la cotización de un swap, prepare un intercambio cross-chain. Pero el agente, por listo que sea, está ciego: no tiene ojos dentro de la blockchain. El camino habitual es enseñarle a llamar a toncenter o tonapi.io por HTTP. Y ahí empieza el dolor: sin clave el límite ronda una petición por segundo, bajo carga llega el HTTP 429 Too Many Requests, los lightservers públicos del config global responden not ready o se caen por timeout de ADNL y sencillamente no guardan historial profundo. Un agente que solo debía «mirar un saldo» tropieza con la infraestructura.

La solución no es enseñarle al agente a llamar a la API a mano, sino darle un servidor MCP para TON. A continuación, la guía completa: qué es MCP, para qué le sirve al agente, cómo conectarse gratis con un solo comando y qué saben hacer las 16 herramientas de TONNode.

Qué es MCP y para qué lo necesita un agente de IA

MCP (Model Context Protocol) es un estándar abierto con el que los agentes de IA invocan herramientas externas. Lo entienden Claude, Cursor, ChatGPT/Codex y cualquier otro cliente MCP: tú declaras un conjunto de herramientas, el agente ve sus descripciones y decide por sí mismo cuál llamar y con qué parámetros.

La analogía es simple: MCP es para el agente lo que un puerto USB para una computadora. El modelo por sí solo no tiene acceso ni a la red ni a la blockchain. Pero conecta un servidor MCP y el agente gana un juego de «enchufes»: leer un saldo, armar una transacción, seguir una operación. Le dices «¿cuánto USDT hay en la wallet X?» y el modelo entiende que necesita la herramienta get_jetton_balance, coloca la dirección y recibe una respuesta estructurada.

La diferencia con «dale al agente un endpoint HTTP» es de fondo. Trabajando contra la API cruda, el agente tiene que mantener en contexto cómo formar las peticiones, cómo parsear las respuestas, cómo convertir direcciones y unidades raw. Todo eso es terreno fértil para alucinaciones. MCP saca esa lógica al servidor: el agente ve una herramienta get_balance con una firma clara y recibe la respuesta lista. Menos errores, menos tokens en el contexto, comportamiento predecible.

TONNode (sitio: tonnode.io) es exactamente eso: un servidor MCP hosted listo para TON (The Open Network). Un único endpoint, 16 herramientas para lectura, swap, cross-chain y gestión de wallets, sobre el protocolo nativo de TON, sin capas HTTP intermedias.

Por qué el agente necesita un servidor MCP para TON y no los gateways HTTP públicos

Pregunta razonable: ¿para qué un servidor aparte si existen APIs públicas como toncenter y tonapi.io? El problema es que los gateways públicos sirven para consultas manuales puntuales, pero no están pensados para la carga de un agente que dispara en bucle decenas de llamadas por minuto.

• Límites y 429. Sin clave, toncenter y tonapi.io dan del orden de una petición por segundo y, si te pasas, responden HTTP 429 Too Many Requests. Un agente en el ciclo «leo el estado → decido → leo más» choca con el techo al instante — y en vez de una respuesta le entrega al usuario un error.
• Los lightservers públicos no son confiables. Los lightservers del config global (si vas a TON por ADNL directo) son compartidos y limitados. Bajo carga responden not ready, se caen por timeout de ADNL y no guardan historial profundo de transacciones.
• Respuesta cruda ≠ respuesta para el agente. Incluso un JSON exitoso suele exigir posprocesado: calcular la dirección de la jetton wallet, convertir las unidades raw según los decimals, pasar la dirección de un formato a otro. Cada paso de esos delegado al modelo es un error potencial y tokens de más.

Un servidor MCP cierra todo esto: throughput estable ligado a tu clave, cálculos del lado del servidor y una interfaz única con respuestas estructuradas listas. Por cierto, si en algún chat te encuentras con el «error 228», ten en cuenta que es un número meme de la comunidad TON, no un código de la API; el código real del rate limit es 429.

El desglose detallado del camino gratuito está en un artículo aparte: cómo conectar TON a tu agente gratis.

Cómo conectarlo: gratis vía npx o con clave hosted

Hay dos caminos, y el primero es completamente gratuito.

Opción 1. Local vía npx (gratis, todas las herramientas de lectura)

El conjunto completo de herramientas de lectura está disponible sin registro y sin clave. El paquete @tonnode/mcp es open source (MIT), está publicado en npm y GitHub (tonnode/mcp) y funciona sobre el protocolo nativo ADNL de TON. Añade a la config de tu cliente MCP:

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

Reinicia Claude Desktop, Cursor o el cliente que uses — las herramientas aparecen solas. La configuración paso a paso para clientes concretos está en la guía cómo conectar Claude y Cursor a TON.

Opción 2. Clave hosted (throughput garantizado)

Cuando el agente corre en producción y el volumen de peticiones es alto, necesitas tu propia clave y un canal estable:

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

La clave gratuita Hobby se emite nada más iniciar sesión, sin tarjeta, y con ella están disponibles las 16 herramientas — tonnode.io/dashboard?plan=hobby.

Las 16 herramientas de TONNode por grupos

Todas las herramientas están disponibles en todos los planes — solo pagas por el throughput. Vamos grupo por grupo.

Lectura (8 herramientas)

La base de cualquier agente que observa la red sin cambiar nada:

• get_masterchain_info — la «cabeza» de la masterchain, el punto actual de la red.
• get_balance — saldo de GRAM en una dirección.
• get_account_state — estado de la cuenta, flags, última transacción.
• get_transactions — historial de transacciones de una dirección.
• run_get_method — llamada a cualquier get-method read-only de un contrato.
• get_jetton_balance — saldo de un jetton (por ejemplo, USDT); la dirección de la jetton wallet se calcula on-chain, no hace falta conocerla de antemano.
• parse_address — conversión y validación de direcciones (EQ/UQ/raw), funciona offline.
• get_jetton_info — metadatos del jetton: nombre, símbolo, emisión y, sobre todo, decimals. Los decimals son críticos para convertir las unidades raw: USDT tiene 6; la mayoría de los jettons, 9.

Ejemplo de prompt para un agente con TONNode conectado:

Revisa el saldo de GRAM y USDT en la wallet UQ… y muéstrame las últimas 5 transacciones.

El agente llamará por sí solo a get_balance, get_jetton_balance (sacando antes los decimals con get_jetton_info) y get_transactions — sin una sola petición HTTP manual.

Swap (2 herramientas)

Intercambio dentro de TON vía el protocolo Omniston, que agrega la liquidez de STON.fi y DeDust:

• get_swap_quote — cotización firme de DEX para el par GRAM ⇄ jetton.
• build_swap_tx — transacción de swap sin firmar, lista para firmarse vía TonConnect.

Fíjate en las palabras «sin firmar» — volveremos a ellas en la sección sobre no custodia.

Cross-chain (5 herramientas)

TON siempre actúa como origen, y el intercambio pasa por un escrow HTLC atómico — un mecanismo donde los fondos se bloquean con el hash de un secreto y solo se desbloquean cuando se cumplen las condiciones en ambas redes. Redes soportadas: Ethereum, Arbitrum, Base, BNB Chain, Polygon, Avalanche. TRON por ahora no está soportado.

• get_crosschain_quote — cotización del intercambio cross-chain.
• build_crosschain_swap_tx — transacción de escrow HTLC sin firmar, más el secreto.
• track_crosschain_swap — fases de la operación en ambas redes.
• disclose_crosschain_secret — revelar el secreto para el settlement tras verificar on-chain que todo está listo.
• build_crosschain_refund — recuperar los fondos del escrow si la operación quedó colgada.

El esquema HTLC significa que el intercambio o se ejecuta de forma atómica o se devuelve vía refund — los fondos no se quedan atascados en manos de un intermediario.

Wallet (1 herramienta)

• generate_wallet — crea una wallet TON nueva en versión v3r2, v4, v5r1 o highload_v3 y devuelve la mnemónica, las claves y la dirección. El servidor no guarda la wallet generada — se te entrega directamente a ti.

El repaso completo de las herramientas con sus parámetros está en tonnode.io/mcp.

No custodia: por qué el servidor nunca tiene tus claves

Esta es la diferencia de fondo, y conviene entenderla antes de acercar al agente al dinero.

Las herramientas de swap, cross-chain y generación de wallets son estrictamente no custodiales. El servidor de TONNode nunca firma transacciones y nunca guarda fondos ni claves privadas. Cuando el agente llama a build_swap_tx o build_crosschain_swap_tx, recibe de vuelta un mensaje TonConnect sin firmar — el borrador de la transacción. Quien firma es la wallet del usuario, no el servidor. Las wallets de generate_wallet también se te entregan a ti y no se quedan en el servidor.

Una analogía: el servidor MCP es el copiloto que traza la ruta y rellena la orden de pago. Pero pulsar «enviar» y estampar la firma solo puedes hacerlo tú, al volante de tu propia wallet. Incluso si el agente está comprometido o se equivoca, no puede llevarse los fondos: en sus manos solo hay borradores sin firmar.

Aquí viene bien la comparación con el @ton/mcp oficial de la TON Foundation. Es un paquete potente y oficial: sabe leer, enviar GRAM/jettons/NFT, hacer swap vía un agregador de DEX, trabajar con NFT y DNS, crear e importar agent wallets. Pero por diseño es una agent wallet custodial con split-key: la clave operator la tiene el propio agente y firma con ella; la clave owner queda en manos del usuario. Y no tiene cross-chain: solo TON. La diferencia es honesta: el paquete oficial le permite al agente gastar fondos de forma autónoma y trabajar con NFT/DNS; TONNode apuesta por la no custodia, el cross-chain y la opción hosted. El análisis detallado está en TONNode frente al TON MCP oficial y MCP custodial frente a no custodial.

Planes y por dónde empezar

En todos los planes están disponibles las 16 herramientas — lo único que cambia es el throughput:

Plan	Precio	Límite
Hobby	gratis para siempre	60 peticiones/min
Pro	$29/mes	300 peticiones/min
Scale	$199/mes	1200 peticiones/min

Pro y Scale se pueden pagar en GRAM o USDT en la red TON vía TonConnect, o en BTC/ETH/SOL y otras monedas mediante una factura de xRocket en Telegram. La clave se emite automáticamente al confirmarse el pago. (Por si acaso: GRAM es el Toncoin renombrado en junio de 2026; la red en sí sigue llamándose TON.)

Un camino práctico para arrancar:

1. Toma la clave gratuita Hobby — sin tarjeta, nada más iniciar sesión, con las 16 herramientas: tonnode.io/dashboard?plan=hobby.
2. Escribe la config hosted (o empieza en local con npx -y @tonnode/mcp).
3. Dale al agente un primer prompt de lectura — saldo, estado de cuenta, historial — y comprueba que el 429 y el not ready ya no estorban.

Después, cuando toques el límite en producción, mira los planes y el repaso de herramientas. Empieza con la clave gratuita y conecta tu agente a TON en un par de minutos.