TONNode MCP

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

@tonnode/mcp

Versão em russo

Servidor MCP que dá a agentes de IA acesso direto a liteservers de The Open Network (TON) — sem gateways HTTP no meio. Saldos, estado de contas, histórico de transações e métodos get de contratos através do protocolo nativo ADNL da TON.

Construído pela TONNode — liteservers privados da TON, nós de arquivo, um stream de mempool e uma API REST (acesso antecipado, sob solicitação).

Início rápido

Adicione ao Claude Desktop, Claude Code, ChatGPT, Cursor, Codex ou qualquer cliente MCP:

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

Essa é a integração completa. O servidor se conecta à mainnet da TON via config global pública por padrão. Configs prontas para cada cliente — além de uso programático em Node.js — estão em examples/.

Ferramentas

Nota sobre nomenclatura: a moeda nativa foi renomeada de Toncoin para GRAM em junho de 2026; a rede em si ainda se chama TON. As saídas das ferramentas usam campos *_gram.

Ferramenta	O que faz	Pergunta típica
get_balance	Saldo de GRAM de um endereço	"Quanto GRAM a EQ… possui?"
get_jetton_balance	Saldo de Jetton/token (USDT e qualquer token TEP-74)	"Quanto USDT há nesta carteira?"
get_jetton_info	Metadados do token: nome, símbolo, decimais, supply	"Quais são os decimais deste jetton?"
get_transactions	Transações recentes: valores, remetentes, taxas	"Meu pagamento chegou?"
get_account_state	Status, flags de deploy, ponteiro da última tx	"Este contrato está implantado?"
run_get_method	Métodos get somente leitura em contratos	"Chame get_jetton_data neste master"
parse_address	Converter/validar formas EQ…/UQ…/raw, offline	"Estes dois endereços são iguais?"
get_masterchain_info	Cabeça da masterchain: seqno, shard, hashes	"A rede (ou meu endpoint) está viva?"
get_swap_quote	Cotação firme de swap DEX (GRAM ⇄ qualquer jetton) via Omniston	"Quanto USDT por 100 GRAM agora?"
build_swap_tx	Transação de swap não assinada, pronta para TonConnect	"Prepare esse swap para minha carteira assinar"
get_crosschain_quote	Cotação TON → Ethereum/Arbitrum/Base/BNB/Polygon/Avalanche	"Quanto USDT na Ethereum pelo meu USDT na TON?"
build_crosschain_swap_tx	Transação de escrow HTLC não assinada + seu segredo	"Inicie esse swap cross-chain"
track_crosschain_swap	Fases ao vivo de uma negociação cross-chain em ambas as chains	"O resolver travou meu USDT na Ethereum?"
disclose_crosschain_secret	Revelar o segredo — liquida ambas as partes atomicamente	"Complete o swap"
build_crosschain_refund	Cancelamento não assinado que recupera fundos em escrow	"A negociação travou — quero meu dinheiro de volta"
generate_wallet	Criar uma nova carteira TON (mnemônico + chaves + endereço)	"Crie uma carteira para meu agente usar"

Geração de carteiras

generate_wallet cria uma carteira nova — um mnemônico de 24 palavras, seu par de chaves ed25519 e o endereço para a versão de contrato escolhida (v4 padrão, além de v3r2, v5r1 e highload_v3 para pagamentos em massa). Os endereços v3r2/v4/v5r1 vêm dos contratos canônicos de @ton/ton; highload_v3 é derivado do código oficial do contrato e verificado contra uma implementação de referência mantida.

⚠️ Isso retorna material de chave secreta. No modo hospedado, as chaves são geradas no servidor e retornadas via TLS — trate toda carteira gerada como quente: ok para uso programático/efêmero, mas mova qualquer saldo significativo para armazenamento frio e mantenha a resposta fora de logs e transcrições compartilhadas. O servidor nunca armazena ou registra o mnemônico ou a chave privada (apenas o endereço público). Operadores podem definir TONNODE_DISABLE_WALLET_GEN=1 para remover a ferramenta completamente.

Swaps — agentes que realmente negociam

get_swap_quote e build_swap_tx são alimentados pela Omniston, o protocolo RFQ da STON.fi que agrega liquidez de STON.fi e DeDust. Nenhuma chave de API necessária.

O fluxo é estritamente não custodial — o servidor nunca vê uma chave privada, nunca assina e nunca transmite:

1. get_swap_quote trava uma cotação firme (valores em unidades indivisíveis brutas; a resposta inclui o piso de slippage, impacto de preço, orçamento de gas e rota DEX).
2. build_swap_tx transforma a cotação em mensagens não assinadas exatamente no formato que tonConnectUi.sendTransaction() espera — assinar e enviar permanecem com o dono da carteira.

Cotações expiram em cerca de um minuto, então construa rapidamente. A Omniston emula a transferência ao construir: se a carteira não tiver o valor de entrada, a construção falha de antemão em vez de queimar gas na chain.

Cross-chain

As ferramentas *_crosschain_* levam a mesma ideia entre blockchains: pague em GRAM ou qualquer jetton da TON, receba USDT/USDC/coins nativas em Ethereum, Arbitrum, Base, BNB, Polygon ou Avalanche — liquidadas através do escrow HTLC atômico da Omniston, tipicamente em bem menos de um minuto. A TON é sempre a chain de origem (o assinante é uma carteira TON).

O agente conduz todo o ciclo de vida do swap atômico: cotação → construção (a ferramenta gera o segredo HTLC e o entrega ao chamador — o servidor não guarda nada) → assinar & enviar → rastrear ambas as chains → divulgar o segredo para liquidar, ou construir um reembolso se a negociação travar. Em nenhum momento o servidor, o resolver ou qualquer outra pessoa pode redirecionar os fundos: o segredo apenas completa a negociação como cotada, e um escrow não preenchido é sempre recuperável pela carteira do dono.

Modo HTTP hospedado / auto-hospedado

O pacote também inclui uma entrada Streamable-HTTP para implantações remotas (é isso que alimenta mcp.tonnode.io):

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

Quer um endpoint hospedado pronto em vez de rodar o seu? Chaves para mcp.tonnode.io são emitidas em tonnode.io/mcp. Clientes se conectam sem instalar nada:

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

Requisições são autenticadas com chaves Bearer e limitadas por taxa por chave (RATE_LIMIT_RPM, padrão 300). Além de Authorization: Bearer <key>, o servidor aceita um Authorization: <key> simples e X-API-Key: <key> — para gateways (ex.: Smithery) que reservam o header Authorization para si. As chaves vêm de TONNODE_KEYS (separadas por vírgula, fixas) ou TONNODE_KEYS_FILE — um array JSON de {"key", "label"?, "rpm"?, "expires"?} que é recarregado a quente em mudança e em SIGHUP: adicione ou revogue chaves de clientes sem reiniciar, limites de taxa por chave e chaves com auto-expiração para planos de assinatura. Sessões ao vivo de uma chave revogada são fechadas imediatamente. GLOBAL_RATE_LIMIT_RPM adiciona um teto total entre todas as chaves para proteger o liteserver de backend. Sessões são privadas à chave que as abriu, sessões ociosas são varridas após SESSION_TTL_MIN (padrão 30 minutos) e sessões concorrentes são limitadas por chave e globalmente. Sem chaves, o servidor se recusa a iniciar; defina TONNODE_ALLOW_OPEN=1 para rodar explicitamente sem chaves atrás do seu próprio firewall. GET /healthz para monitoramento, deploy/tonnode-keys.sh para gerenciamento de chaves.

O servidor vincula 127.0.0.1 por padrão — coloque um proxy reverso TLS (Caddy, nginx) na frente e defina HOST=0.0.0.0 apenas se o proxy rodar em outra máquina. Configs prontas de systemd + Caddy estão em deploy/.

Configuração

Variável de ambiente	Significado
TON_LITESERVERS	Use seus próprios liteservers em vez da config pública: [{"ip":"1.2.3.4","port":40004,"key":"<base64 ed25519>"}]
TON_CONFIG_URL	URL alternativa da config global
TON_NETWORK=testnet	Use a config de testnet (ou passe --testnet)
TONNODE_KEYS	Modo HTTP: chaves de API Bearer separadas por vírgula (simples, fixas)
TONNODE_KEYS_FILE	Modo HTTP: arquivo JSON de chaves com rótulos, rpm por chave, expires — recarregado a quente
HOST	Modo HTTP: endereço de bind (padrão 127.0.0.1)
PORT	Modo HTTP: porta de escuta (padrão 8808)
RATE_LIMIT_RPM	Modo HTTP: requisições padrão por minuto por chave (padrão 300)
GLOBAL_RATE_LIMIT_RPM	Modo HTTP: teto total entre todas as chaves (padrão desligado)
SESSION_TTL_MIN	Modo HTTP: minutos ociosos antes de uma sessão ser varrida (padrão 30)
MAX_SESSIONS / MAX_SESSIONS_PER_KEY	Modo HTTP: limites de sessões concorrentes (padrão 500 / 50)
OMNISTON_API_URL	Ferramentas de swap: endpoint WebSocket alternativo da Omniston (padrão wss://omni-ws.ston.fi)
OMNISTON_INTEGRATOR_ADDRESS / OMNISTON_INTEGRATOR_FEE_BPS	Ferramentas de swap: participação opcional de receita do integrador em bps da saída — sempre visível ao chamador como integrator_fee_units em cada cotação (padrão desligado)
TONNODE_DISABLE_WALLET_GEN	Defina como 1 para remover a ferramenta generate_wallet (ex.: em um endpoint hospedado compartilhado onde você não quer material de chave gerado no servidor)

Uma nota sobre liteservers públicos

Os liteservers públicos da config padrão são compartilhados, limitados por taxa e não mantêm histórico profundo — get_transactions além de blocos recentes responderá lt not in db. Agentes também tendem a consultar em rajadas, o que gateways públicos limitam.

Para seu próprio limite de taxa e histórico de arquivo, aponte TON_LITESERVERS para um liteserver privado — um par de chaves e um global.config.json do console, pagos a partir de um saldo financiado em GRAM ou USDT. Como o arquivo de config, as chaves ADNL e o roteamento de arquivo funcionam é coberto no guia de Liteserver da TON.

Stream de mempool

Mensagens pendentes não são expostas através deste servidor MCP — nenhuma das ferramentas acima lê o mempool. A TONNode oferece o mempool como um feed WebSocket separado em wss://mempool.tonnode.io/v1/stream: um objeto JSON por mensagem externa conforme o nó da TONNode a recebe do overlay público, antes de entrar em um bloco, com filtros por carteira de destino, op code ou pool DEX e um replay curto após reconexão. Planos são precificados pelo número de conexões simultâneas em uma chave. A cobertura é parcial — o nó vê apenas o que chega a ele pelo overlay, e nenhuma garantia de completude ou velocidade é prometida — e mensagens enviadas através dos liteservers da TONNode geralmente não aparecem nele (o nó não publica suas próprias transmissões; uma cópia retransmitida por outros nós apareceu em 2 de 20 envios em um teste em 8 de outubro de 2026). Protocolo, chaves e planos: tonnode.io/en/docs/mempool.

Licença

MIT © TONNode