TONNode MCP

Servidor MCP para TON sobre liteservers ADNL nativos: saldos, jettons, historial de transacciones, get-methods, construcción de DEX no custodial y swaps entre cadenas, generación de wallets.

GitHub

Servidor MCP alojado

npx add-mcp 'https://mcp.tonnode.io/mcp'

Se instala en Claude Code, Codex, Cursor y más

Documentación

@tonnode/mcp

Русская версия

Servidor MCP que brinda a los agentes de IA acceso directo a liteservers de The Open Network (TON) — sin puertas de enlace HTTP en el medio. Saldos, estado de cuentas, historial de transacciones y métodos get de contratos a través del protocolo nativo ADNL de TON.

Creado por TONNode — liteservers privados de TON, nodos de archivo, un flujo de mempool y una API REST (acceso anticipado, bajo solicitud).

Inicio rápido

Agrégalo a Claude Desktop, Claude Code, ChatGPT, Cursor, Codex o cualquier cliente MCP:

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

Esa es toda la integración. El servidor se conecta a la red principal de TON mediante la configuración global pública por defecto. Configuraciones listas para cada cliente — además del uso programático con Node.js — están en examples/.

Herramientas

Nota sobre nombres: la moneda nativa fue renombrada de Toncoin a GRAM en junio de 2026; la red en sí sigue llamándose TON. Las salidas de las herramientas usan campos *_gram.

Herramienta	Qué hace	Pregunta típica
`get_balance`	Saldo de GRAM de una dirección	"¿Cuánto GRAM tiene EQ…?"
`get_jetton_balance`	Saldo de Jetton/token (USDT y cualquier token TEP-74)	"¿Cuánto USDT hay en esta billetera?"
`get_jetton_info`	Metadatos del token: nombre, símbolo, decimales, suministro	"¿Cuáles son los decimales de este jetton?"
`get_transactions`	Transacciones recientes: valores, remitentes, comisiones	"¿Llegó mi pago?"
`get_account_state`	Estado, indicadores de despliegue, puntero de última transacción	"¿Está desplegado este contrato?"
`run_get_method`	Métodos get de solo lectura en contratos	"Llama a `get_jetton_data` en este master"
`parse_address`	Convertir/validar formas EQ…/UQ…/raw, sin conexión	"¿Son estas dos direcciones iguales?"
`get_masterchain_info`	Cabecera de la masterchain: seqno, shard, hashes	"¿Está viva la red (o mi endpoint)?"
`get_swap_quote`	Cotización firme de swap DEX (GRAM ⇄ cualquier jetton) vía Omniston	"¿Cuánto USDT por 100 GRAM ahora mismo?"
`build_swap_tx`	Transacción de swap sin firmar, lista para TonConnect	"Prepara ese swap para que mi billetera lo firme"
`get_crosschain_quote`	Cotización TON → Ethereum/Arbitrum/Base/BNB/Polygon/Avalanche	"¿Cuánto USDT en Ethereum por mi USDT en TON?"
`build_crosschain_swap_tx`	Transacción de custodia HTLC sin firmar + su secreto	"Inicia ese swap entre cadenas"
`track_crosschain_swap`	Fases en vivo de un intercambio entre cadenas en ambas cadenas	"¿El resolver bloqueó mi USDT en Ethereum?"
`disclose_crosschain_secret`	Revela el secreto — liquida ambas partes atómicamente	"Completa el swap"
`build_crosschain_refund`	Cancelación sin firmar que recupera los fondos en custodia	"El intercambio se detuvo — recupera mi dinero"
`generate_wallet`	Genera una billetera TON nueva (mnemónico + claves + dirección)	"Crea una billetera para que mi agente la use"

Generación de billeteras

generate_wallet genera una billetera completamente nueva — un mnemónico de 24 palabras, su par de claves ed25519 y la dirección para la versión de contrato elegida (v4 por defecto, además de v3r2, v5r1 y highload_v3 para pagos masivos). Las direcciones v3r2/v4/v5r1 provienen de los contratos canónicos de @ton/ton; highload_v3 se deriva del código oficial del contrato y se verifica contra una implementación de referencia mantenida.

⚠️ Esto devuelve material de clave secreta. En modo alojado, las claves se generan en el servidor y se devuelven a través de TLS — trata cada billetera generada como caliente: adecuada para uso programático/efímero, pero mueve cualquier saldo significativo a almacenamiento en frío y mantén la respuesta fuera de registros y transcripciones compartidas. El servidor nunca almacena ni registra el mnemónico o la clave privada (solo la dirección pública). Los operadores pueden configurar TONNODE_DISABLE_WALLET_GEN=1 para eliminar la herramienta por completo.

Swaps — agentes que realmente pueden operar

get_swap_quote y build_swap_tx están impulsados por Omniston, el protocolo RFQ de STON.fi que agrega liquidez de STON.fi y DeDust. No se necesita clave API.

El flujo es estrictamente sin custodia — el servidor nunca ve una clave privada, nunca firma y nunca transmite:

get_swap_quote bloquea una cotización firme (montos en unidades indivisibles raw; la respuesta incluye el piso de deslizamiento, el impacto en el precio, el presupuesto de gas y la ruta DEX).
build_swap_tx convierte la cotización en mensajes sin firmar exactamente en la forma que tonConnectUi.sendTransaction() espera — firmar y enviar queda en manos del propietario de la billetera.

Las cotizaciones expiran en aproximadamente un minuto, así que construye con prontitud. Omniston emula la transferencia al construir: si la billetera no tiene el monto de entrada, la construcción falla de inmediato en lugar de quemar gas en la cadena.

Entre cadenas

Las herramientas *_crosschain_* llevan la misma idea a través de blockchains: paga en GRAM o cualquier jetton de TON, recibe USDT/USDC/monedas nativas en Ethereum, Arbitrum, Base, BNB, Polygon o Avalanche — liquidadas mediante la custodia atómica HTLC de Omniston, típicamente en menos de un minuto. TON es siempre la cadena de origen (el firmante es una billetera TON).

El agente impulsa todo el ciclo de vida del swap atómico: cotizar → construir (la herramienta genera el secreto HTLC y lo entrega al llamante — el servidor no guarda nada) → firmar y enviar → rastrear ambas cadenas → revelar el secreto para liquidar, o construir un reembolso si el intercambio se detiene. En ningún momento el servidor, el resolver o cualquier otra persona puede redirigir los fondos: el secreto solo completa el intercambio tal como se cotizó, y una custodia no cumplida siempre es recuperable por la billetera propietaria.

Modo HTTP alojado / autoalojado

El paquete también incluye una entrada Streamable-HTTP para despliegues remotos (esto es lo que impulsa mcp.tonnode.io):

TONNODE_KEYS=tn_live_abc,tn_live_def PORT=8808 npx -y @tonnode/mcp --http

¿Quieres un endpoint alojado listo en lugar de ejecutar el tuyo? Las claves para mcp.tonnode.io se emiten en tonnode.io/mcp. Los clientes se conectan sin instalar nada:

{
  "mcpServers": {
    "ton": {
      "url": "https://your-host/mcp",
      "headers": { "Authorization": "Bearer tn_live_abc" }
    }
  }
}

Las solicitudes se autentican con claves Bearer y tienen límite de tasa por clave (RATE_LIMIT_RPM, 300 por defecto). Además de Authorization: Bearer <key>, el servidor acepta un Authorization: <key> simple y X-API-Key: <key> — para puertas de enlace (por ejemplo, Smithery) que reservan el encabezado Authorization para sí mismas. Las claves provienen de TONNODE_KEYS (separadas por comas, fijas) o de TONNODE_KEYS_FILE — un archivo JSON de {"key", "label"?, "rpm"?, "expires"?} que se recarga en caliente al cambiar y con SIGHUP: agrega o revoca claves de clientes sin reiniciar, límites de tasa por clave y claves con autoexpiración para planes de suscripción. Las sesiones activas de una clave revocada se cierran de inmediato. GLOBAL_RATE_LIMIT_RPM agrega un tope total entre todas las claves para proteger el liteserver de backend. Las sesiones son privadas para la clave que las abrió, las sesiones inactivas se eliminan después de SESSION_TTL_MIN (30 minutos por defecto) y las sesiones concurrentes tienen un tope por clave y global. Sin claves, el servidor se niega a iniciar; configura TONNODE_ALLOW_OPEN=1 para ejecutarlo explícitamente sin claves detrás de tu propio firewall. GET /healthz para monitoreo, deploy/tonnode-keys.sh para gestión de claves.

El servidor se vincula a 127.0.0.1 por defecto — coloca un proxy inverso TLS (Caddy, nginx) al frente y configura HOST=0.0.0.0 solo si el proxy se ejecuta en otra máquina. Configuraciones listas de systemd + Caddy están en deploy/.

Configuración

Variable de entorno	Significado
`TON_LITESERVERS`	Usa tus propios liteservers en lugar de la configuración pública: `[{"ip":"1.2.3.4","port":40004,"key":"<base64 ed25519>"}]`
`TON_CONFIG_URL`	URL alternativa de configuración global
`TON_NETWORK=testnet`	Usa la configuración de testnet (o pasa `--testnet`)
`TONNODE_KEYS`	Modo HTTP: claves API Bearer separadas por comas (simple, fijas)
`TONNODE_KEYS_FILE`	Modo HTTP: archivo JSON de claves con etiquetas, `rpm` por clave, `expires` — recargado en caliente
`HOST`	Modo HTTP: dirección de vinculación (por defecto `127.0.0.1`)
`PORT`	Modo HTTP: puerto de escucha (por defecto 8808)
`RATE_LIMIT_RPM`	Modo HTTP: solicitudes por minuto por clave por defecto (300 por defecto)
`GLOBAL_RATE_LIMIT_RPM`	Modo HTTP: tope total entre todas las claves (por defecto desactivado)
`SESSION_TTL_MIN`	Modo HTTP: minutos de inactividad antes de eliminar una sesión (30 por defecto)
`MAX_SESSIONS` / `MAX_SESSIONS_PER_KEY`	Modo HTTP: límites de sesiones concurrentes (500 / 50 por defecto)
`OMNISTON_API_URL`	Herramientas de swap: endpoint WebSocket alternativo de Omniston (por defecto `wss://omni-ws.ston.fi`)
`OMNISTON_INTEGRATOR_ADDRESS` / `OMNISTON_INTEGRATOR_FEE_BPS`	Herramientas de swap: participación opcional en ingresos del integrador en bps de la salida — siempre visible para el llamante como `integrator_fee_units` en cada cotización (por defecto desactivado)
`TONNODE_DISABLE_WALLET_GEN`	Configúralo a `1` para eliminar la herramienta `generate_wallet` (por ejemplo, en un endpoint alojado compartido donde no quieras generar material de clave en el servidor)

Nota sobre liteservers públicos

Los liteservers de configuración pública por defecto son compartidos, tienen límite de tasa y no guardan historial profundo — get_transactions más allá de bloques recientes responderá lt not in db. Los agentes también tienden a consultar en ráfagas, que las puertas de enlace públicas limitan.

Para tu propio límite de tasa e historial de archivo, apunta TON_LITESERVERS a un liteserver privado — un par de claves y un global.config.json desde la consola, pagado desde un saldo financiado en GRAM o USDT. Cómo funcionan el archivo de configuración, las claves ADNL y el enrutamiento de archivo se cubren en la guía de TON Liteserver.

Flujo de mempool

Los mensajes pendientes no se exponen a través de este servidor MCP — ninguna de las herramientas anteriores lee el mempool. TONNode ofrece el mempool como un feed WebSocket separado en wss://mempool.tonnode.io/v1/stream: un objeto JSON por mensaje externo cuando el nodo de TONNode lo recibe del overlay público, antes de que aterrice en un bloque, con filtros por billetera de destino, código de operación o pool DEX y una breve reproducción después de una reconexión. Los planes se cobran según el número de conexiones simultáneas en una clave. La cobertura es parcial — el nodo solo ve lo que le llega a través del overlay, y no se prometen cifras de completitud o velocidad — y los mensajes enviados a través de los liteservers de TONNode generalmente no aparecen en él (el nodo no publica sus propias transmisiones; una copia retransmitida por otros nodos apareció en 2 de 20 envíos en una prueba el 8 de octubre de 2026). Protocolo, claves y planes: tonnode.io/en/docs/mempool.