TON MCP : donner à un agent IA l'accès à TON — le guide complet

Vous avez un agent IA — Claude dans Cursor, un script piloté par Codex, un bot maison — et vous voulez qu'il travaille réellement avec TON : vérifier le solde d'un wallet avant un envoi, lire l'historique des transactions, calculer une cotation de swap, préparer un échange cross-chain. Mais l'agent, aussi malin soit-il, est aveugle : il n'a aucun œil sur la blockchain. La voie classique consiste à lui apprendre à appeler toncenter ou tonapi.io en HTTP. Et c'est là que les ennuis commencent : sans clé, la limite tourne autour d'une requête par seconde, sous charge vous récupérez un HTTP 429 Too Many Requests, les liteservers publics de la config globale répondent not ready ou tombent en timeout ADNL, et ils n'ont tout simplement pas d'historique profond. L'agent qui devait « juste regarder un solde » trébuche sur l'infrastructure.

La solution n'est pas d'apprendre à l'agent à appeler les API à la main, mais de lui donner un serveur MCP pour TON. Voici le guide complet : ce qu'est MCP, à quoi il sert pour un agent, comment se connecter gratuitement en une seule commande et ce que savent faire les 16 outils TONNode.

Ce qu'est MCP et pourquoi un agent IA en a besoin

MCP (Model Context Protocol) est un standard ouvert par lequel les agents IA appellent des outils externes. Claude, Cursor, ChatGPT/Codex et n'importe quel autre client MCP le comprennent : vous déclarez un ensemble d'outils, l'agent voit leurs descriptions et décide lui-même lequel appeler et avec quels paramètres.

L'analogie est simple : MCP est à l'agent ce que le port USB est à l'ordinateur. Le modèle, en soi, n'a accès ni au réseau ni à la blockchain. Branchez un serveur MCP, et l'agent dispose d'un jeu de « prises » : lire un solde, assembler une transaction, suivre un échange. Vous dites « combien d'USDT sur le wallet X » — le modèle comprend qu'il lui faut l'outil get_jetton_balance, y renseigne l'adresse et reçoit une réponse structurée.

La différence avec « donnez un endpoint HTTP à l'agent » est fondamentale. En passant par une API brute, l'agent doit garder en contexte comment construire les requêtes, comment parser les réponses, comment convertir les adresses et les unités raw. Autant d'occasions d'halluciner. MCP déporte cette logique côté serveur : l'agent voit un outil get_balance avec une signature claire et reçoit une réponse prête à l'emploi. Moins d'erreurs, moins de tokens dans le contexte, un comportement prévisible.

TONNode (site tonnode.io) est justement un serveur MCP hébergé, prêt à l'emploi, pour TON (The Open Network). Un seul endpoint, 16 outils couvrant la lecture, le swap, le cross-chain et les wallets, au-dessus du protocole natif de TON, sans couches HTTP intermédiaires.

Pourquoi un serveur MCP pour TON plutôt que les passerelles HTTP publiques

Question légitime : pourquoi un serveur dédié, alors qu'il existe des API publiques comme toncenter et tonapi.io ? Le problème, c'est que les passerelles publiques conviennent aux requêtes manuelles ponctuelles, mais ne sont pas conçues pour la charge d'un agent qui enchaîne en boucle des dizaines d'appels par minute.

• Limites et 429. Sans clé, toncenter et tonapi.io plafonnent à environ une requête par seconde et répondent HTTP 429 Too Many Requests en cas de dépassement. Un agent dans une boucle « lire l'état → décider → relire » atteint le plafond instantanément — et renvoie à l'utilisateur une erreur au lieu d'une réponse.
• Les liteservers publics ne sont pas fiables. Les liteservers de la config globale (si vous interrogez TON directement en ADNL) sont partagés et limités. Sous charge, ils répondent not ready, tombent en timeout ADNL et ne conservent pas d'historique profond des transactions.
• Réponse brute ≠ réponse pour l'agent. Même un JSON réussi demande souvent un post-traitement : calculer l'adresse du jetton-wallet, convertir les unités raw selon les decimals, passer une adresse d'un format à l'autre. Chaque étape déléguée au modèle, c'est une erreur potentielle de plus et des tokens gaspillés.

Un serveur MCP règle tout cela : un débit stable rattaché à votre clé, des calculs côté serveur et une interface unique avec des réponses structurées prêtes à l'emploi. Au passage : si vous croisez « l'erreur 228 » dans les chats, c'est un mème de la communauté TON, pas un code d'API ; le vrai code de rate-limit est bien 429.

Le parcours gratuit est détaillé dans une note dédiée : comment connecter TON à votre agent gratuitement.

Comment se connecter : gratuitement via npx ou avec une clé hébergée

Il existe deux chemins, et le premier est entièrement gratuit.

Option 1. En local via npx (gratuit, lecture complète)

L'ensemble complet des outils de lecture est disponible sans inscription et sans clé. Le paquet @tonnode/mcp est open source (MIT), publié sur npm et GitHub (tonnode/mcp), et fonctionne via ADNL, le protocole natif de TON. Ajoutez ceci à la config de votre client MCP :

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

Redémarrez Claude Desktop, Cursor ou tout autre client — les outils apparaissent d'eux-mêmes. La configuration pas à pas pour chaque client se trouve dans le guide comment connecter Claude et Cursor à TON.

Option 2. Clé hébergée (débit garanti)

Quand l'agent tourne en production et que les requêtes s'accumulent, il vous faut votre propre clé et un canal stable :

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

La clé gratuite Hobby est délivrée immédiatement après connexion, sans carte bancaire, et donne accès aux 16 outils — tonnode.io/dashboard?plan=hobby.

Les 16 outils TONNode, groupe par groupe

Tous les outils sont disponibles sur tous les plans — vous ne payez que le débit. Passons-les en revue, groupe par groupe.

Lecture (8 outils)

Le socle de tout agent qui observe le réseau sans rien modifier :

• get_masterchain_info — la « tête » de la masterchain, le point courant du réseau.
• get_balance — le solde en GRAM d'une adresse.
• get_account_state — le statut du compte, ses flags, sa dernière transaction.
• get_transactions — l'historique des transactions d'une adresse.
• run_get_method — l'appel de n'importe quel get-method read-only d'un contrat.
• get_jetton_balance — le solde d'un jetton (par exemple USDT) ; l'adresse du jetton-wallet est calculée on-chain, inutile de la connaître à l'avance.
• parse_address — la conversion et la validation d'adresses (EQ/UQ/raw), fonctionne hors ligne.
• get_jetton_info — les métadonnées d'un jetton : nom, symbole, supply et surtout decimals. Les decimals sont critiques pour convertir les unités raw : USDT en a 6, la plupart des jettons en ont 9.

Exemple de prompt pour un agent avec TONNode branché :

Vérifie le solde GRAM et USDT du wallet UQ… et montre-moi les 5 dernières transactions.

L'agent appellera de lui-même get_balance, get_jetton_balance (après avoir récupéré les decimals via get_jetton_info) et get_transactions — sans la moindre requête HTTP manuelle.

Swap (2 outils)

L'échange à l'intérieur de TON passe par le protocole Omniston, qui agrège la liquidité de STON.fi et DeDust :

• get_swap_quote — une cotation DEX ferme pour une paire GRAM ⇄ jetton.
• build_swap_tx — une transaction de swap non signée, prête à être signée via TonConnect.

Retenez le mot « non signée » — nous y reviendrons dans la section sur le non-custodial.

Cross-chain (5 outils)

TON est toujours la chaîne source, et l'échange passe par un escrow HTLC atomique — un mécanisme où les fonds sont verrouillés par le hash d'un secret et ne se débloquent que si les conditions sont remplies sur les deux réseaux. Réseaux pris en charge : Ethereum, Arbitrum, Base, BNB Chain, Polygon, Avalanche. TRON n'est pas encore supporté.

• get_crosschain_quote — la cotation d'un échange cross-chain.
• build_crosschain_swap_tx — la transaction d'escrow HTLC non signée, plus le secret.
• track_crosschain_swap — les phases de l'échange sur les deux réseaux.
• disclose_crosschain_secret — révéler le secret pour le règlement, après vérification on-chain que tout est prêt.
• build_crosschain_refund — récupérer les fonds de l'escrow si l'échange reste bloqué.

Avec le schéma HTLC, soit l'échange aboutit de façon atomique, soit les fonds repartent via le refund — ils ne restent jamais coincés chez un intermédiaire.

Wallet (1 outil)

• generate_wallet — crée un nouveau wallet TON en version v3r2, v4, v5r1 ou highload_v3 et renvoie la phrase mnémonique, les clés et l'adresse. Le serveur ne conserve pas le wallet généré — il vous est remis immédiatement.

La revue complète des outils avec leurs paramètres se trouve sur la page tonnode.io/mcp.

Non-custodial : pourquoi le serveur ne détient jamais vos clés

C'est la différence fondamentale, et il faut la comprendre avant de laisser un agent s'approcher de votre argent.

Les outils de swap, de cross-chain et de génération de wallet sont strictement non-custodial. Le serveur TONNode ne signe jamais de transactions et ne détient jamais de fonds ni de clés privées. Quand l'agent appelle build_swap_tx ou build_crosschain_swap_tx, il reçoit en retour un message TonConnect non signé — un brouillon de transaction. C'est le wallet de l'utilisateur qui le signe, pas le serveur. Les wallets issus de generate_wallet vous sont eux aussi remis directement et ne restent pas sur le serveur.

Une analogie : le serveur MCP est le copilote qui trace l'itinéraire et pré-remplit l'ordre de virement. Mais appuyer sur « envoyer » et apposer la signature, vous seul le pouvez, au volant de votre wallet. Même si l'agent est compromis ou se trompe, il ne peut pas détourner les fonds — il n'a entre les mains que des brouillons non signés.

La comparaison avec le @ton/mcp officiel de la TON Foundation est utile ici. C'est un paquet solide et officiel : il gère la lecture, l'envoi de GRAM/jettons/NFT, le swap via un agrégateur DEX, les NFT et le DNS, ainsi que la création et l'import d'agent-wallets. Mais par construction, c'est un agent-wallet custodial en split-key : la clé operator est détenue par l'agent lui-même, qui s'en sert pour signer, tandis que la clé owner reste chez l'utilisateur. Et il n'a pas de cross-chain — TON uniquement. La différence est honnête : le paquet officiel permet à l'agent de dépenser de façon autonome et de gérer NFT/DNS ; TONNode mise sur le non-custodial, le cross-chain et l'option hébergée. L'analyse détaillée se trouve dans TONNode face au TON MCP officiel et MCP custodial contre non-custodial.

Tarifs et par où commencer

Les 16 outils sont disponibles sur tous les plans — seul le débit change :

Plan	Prix	Limite
Hobby	gratuit pour toujours	60 requêtes/min
Pro	29 $/mois	300 requêtes/min
Scale	199 $/mois	1200 requêtes/min

Vous pouvez régler Pro et Scale en GRAM ou en USDT sur le réseau TON via TonConnect, ou bien en BTC/ETH/SOL et d'autres devises via une facture xRocket dans Telegram. La clé est délivrée automatiquement une fois le paiement confirmé. (Au cas où : GRAM est le nouveau nom de Toncoin depuis juin 2026 ; le réseau, lui, s'appelle toujours TON.)

Le chemin pragmatique pour démarrer :

1. Prenez la clé gratuite Hobby — sans carte bancaire, dès la connexion, avec les 16 outils : tonnode.io/dashboard?plan=hobby.
2. Renseignez la config hébergée (ou commencez en local avec npx -y @tonnode/mcp).
3. Donnez à l'agent un premier prompt en lecture — solde, état de compte, historique — et constatez que les 429 et les not ready ne vous gênent plus.

Ensuite, quand vous atteindrez la limite en production, jetez un œil aux tarifs et à la revue des outils. Commencez avec la clé gratuite et branchez votre agent à TON en quelques minutes.