TON MCP : connecter Claude et Cursor à TON pas à pas

Tous ceux qui ont essayé de faire faire quelque chose à un agent IA sur TON connaissent ce mur. Vous demandez à Claude de vérifier le solde d'un wallet — il répond honnêtement qu'il n'a pas accès au réseau, ou pire : il invente une adresse de jetton, confond les nanotons avec les tons et sort des chiffres de nulle part. Vous lui donnez un curl vers l'API publique — sous charge, c'est HTTP 429 Too Many Requests qui tombe, et sans clé la limite est d'environ une requête par seconde. Les lightservers publics de la config globale tantôt répondent not ready, tantôt lâchent en timeout ADNL. Le problème ne vient pas du modèle : l'agent n'a tout simplement pas de mains pour toucher la blockchain. MCP lui donne précisément ces mains.

Ci-dessous : comment connecter Claude à TON en quelques minutes, et comment configurer Cursor TON MCP, Claude Code et Codex — les configs exactes, le lancement gratuit via npx et le passage à une clé hosted quand vous atteindrez les limites.

Qu'est-ce que MCP et pourquoi votre agent en a besoin pour TON

MCP (Model Context Protocol) est un standard ouvert qui permet aux agents IA d'appeler des outils externes. Pensez à l'USB : avant, chaque périphérique avait son propre connecteur ; aujourd'hui, un seul port pour tout. MCP est ce même « connecteur universel » entre l'agent et le monde extérieur. Claude Desktop, Claude Code, Cursor, ChatGPT/Codex et n'importe quel autre client MCP parlent la même langue : le client se connecte à un serveur MCP, récupère la liste des outils et les appelle à la demande du modèle.

Pour que l'agent sache interroger le réseau TON, il faut un serveur MCP qui sait le faire. Nous prendrons TONNode, un serveur MCP hosted pour TON. Il donne à l'agent exactement 16 outils : lecture du réseau (solde, état de compte, transactions, get-méthodes des contrats, soldes et métadonnées des jettons), swap via le protocole DEX Omniston, swaps cross-chain par escrow atomique HTLC et génération de wallets. Les outils de swap, de cross-chain et de wallet sont strictement non-custodiaux : le serveur ne signe jamais de transactions et ne détient jamais de clés — il renvoie des messages TonConnect non signés, que le wallet de l'utilisateur signe lui-même.

Pour ce guide, quatre outils de lecture suffisent à vérifier la connexion :

• get_masterchain_info — la tête de la masterchain (le moyen le plus rapide de s'assurer que le serveur est vivant) ;
• get_balance — le solde en GRAM d'une adresse ;
• get_jetton_balance — le solde d'un jetton (USDT et autres), le jetton-wallet est calculé on-chain ;
• parse_address — conversion et validation des adresses EQ/UQ/raw, entièrement hors ligne.

Connecter Claude à TON : démarrage rapide via npx (une seule commande)

Rien à installer. Le serveur local se lance en une commande :

npx -y @tonnode/mcp

Le paquet @tonnode/mcp est open source (MIT), disponible sur npm et GitHub (tonnode/mcp), et parle le protocole natif ADNL de TON sans couche HTTP intermédiaire. La config publique donne gratuitement l'ensemble complet des outils de lecture — de quoi laisser l'agent lire les soldes, les transactions, l'état des comptes et appeler les get-méthodes.

La config de base que vous collerez dans vos clients ressemble à ceci :

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

Retenez bien la structure mcpServers : elle se répète quasiment à l'identique dans tous les clients. La suite ne fait que montrer où la placer. Pour un tour détaillé du mode gratuit, voir le guide dédié MCP pour TON gratuitement.

Pas envie d'installer en local ? La clé gratuite Hobby pour l'endpoint hosted est délivrée dès la connexion, sans carte bancaire — récupérez-la sur tonnode.io/dashboard et collez-la directement dans la config plus bas.

Claude Desktop : où se trouve claude_desktop_config.json et quoi y mettre

Claude Desktop lit sa config MCP dans le fichier claude_desktop_config.json. Le chemin dépend du système :

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

Ouvrez le fichier (ou créez-le s'il n'existe pas) et insérez le fameux objet mcpServers :

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

Après la modification, relancez l'application — Claude Desktop ne lit la config qu'au démarrage. Le serveur ton apparaîtra dans le menu des outils. Écrivez maintenant dans le chat :

Appelle get_masterchain_info et montre-moi le seqno de la tête de la masterchain.

Si l'agent renvoie un numéro de bloc, MCP est connecté. Vous pouvez aussi demander « Vérifie le solde du wallet UQ… » — sous le capot, c'est get_balance qui s'exécute et renvoie un vrai chiffre en GRAM (GRAM est le nouveau nom du Toncoin depuis juin 2026 ; le réseau, lui, s'appelle toujours TON).

Claude Code : la commande claude mcp add et le fichier .mcp.json

Dans Claude Code, le serveur s'ajoute en une seule commande depuis le terminal — elle écrit elle-même tout au bon endroit. Variante locale :

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

Le double tiret -- sépare la commande de lancement du serveur des flags de la commande claude elle-même. Claude Code créera ensuite (ou complétera) le .mcp.json du projet. Si vous préférez, le même objet mcpServers peut être écrit à la main dans le fichier — le résultat est identique :

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

Vérifiez la connexion directement dans le CLI :

Avec parse_address, convertis 0:83df... au format user-friendly EQ/UQ.

parse_address fonctionne hors ligne, c'est donc le test le plus fiable : il ne dépend pas de l'état du réseau et montre instantanément que l'agent voit bien les outils.

Cursor : le fichier .cursor/mcp.json (projet et global)

Bonne nouvelle pour ceux qui ont déjà configuré Claude Desktop : Cursor utilise exactement le même format mcpServers. La config se copie telle quelle — rien à réécrire. La seule différence, c'est l'emplacement du fichier :

• .cursor/mcp.json à la racine du projet — le serveur n'est visible que dans ce projet ;
• ~/.cursor/mcp.json — global, visible dans tous les projets.

En cas de conflit, le fichier projet l'emporte. On y met :

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

Et voilà tout le setup Cursor TON MCP : un fichier, quatre lignes utiles. Après l'enregistrement, vérifiez dans Settings → MCP que ton est bien au statut Enabled, puis demandez à l'agent directement dans l'éditeur :

Combien d'USDT sur le wallet EQ... ? Appelle get_jetton_balance.

get_jetton_balance calcule lui-même l'adresse du jetton-wallet on-chain — inutile de la déterminer à la main. Un article dédié explique comment obtenir le solde USDT en un seul appel.

Codex CLI : config.toml et la commande codex mcp add

Codex fait bande à part : sa config est du TOML, pas du JSON, et elle vit dans ~/.codex/config.toml. La structure est différente, le sens reste le même. En local, le plus simple est la commande :

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

Dans le fichier, cela donne :

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

Pour l'endpoint hosted, Codex ne se configure que via config.toml — le bloc prêt à l'emploi avec url et l'en-tête Authorization est montré dans la section sur la clé hosted ci-dessous. Si vous éditez le TOML à la main, gardez en tête que la syntaxe ici n'est pas faite d'accolades mais de sections entre crochets : copier mécaniquement le JSON de Cursor ne fonctionnera pas. Une fois le serveur ajouté, lancez codex et demandez un appel à get_masterchain_info — une réponse avec le seqno confirmera la connexion.

Quand passer à la clé hosted mcp.tonnode.io et comment l'insérer

Le serveur npx local est parfait pour essayer et monter un prototype. Mais il a un plafond : il passe par les lightservers publics de TON issus de la config globale. Ils sont partagés et limités — sous charge, ils répondent souvent not ready ou partent en timeout ADNL, et ils ne conservent pas d'historique profond. Dès que l'agent commence à travailler sérieusement — servir des utilisateurs, interroger des soldes en boucle, appeler des dizaines de get-méthodes — vous butez sur ces limites.

La différence se voit sur un cas simple. Imaginons qu'une fois par minute, l'agent parcoure une liste d'une cinquantaine de wallets et appelle pour chacun get_balance plus get_jetton_balance — déjà une centaine d'appels par passage. Sur la config publique, cette boucle butera presque à coup sûr sur la limite d'environ une requête par seconde : une partie des adresses renverra not ready, une autre tombera en timeout, et l'agent devra rejouer les requêtes, chargeant encore davantage le lightserver partagé. Sur l'endpoint hosted avec votre propre clé, la même centaine d'appels tient dans la bande passante qui vous est réservée, et l'historique comme l'état des comptes sont servis de façon stable, sans course à la ressource commune.

Il est alors temps de passer à l'endpoint hosted mcp.tonnode.io avec votre propre clé et un débit garanti. La clé au format tn_live_… est un token Bearer pour https://mcp.tonnode.io/mcp. La config hosted change de transport : au lieu de lancer un processus, on indique HTTP et l'en-tête d'autorisation :

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

Pour Claude Code, il y a une commande — notez que les flags viennent avant le nom du serveur :

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

Pour Codex, l'endpoint hosted s'écrit dans ~/.codex/config.toml — l'en-tête d'autorisation se définit dans une section séparée :

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

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

Un point important sur l'honnêteté des tarifs : les 16 outils sont disponibles sur tous les plans, y compris le Hobby gratuit. La clé ne détermine que le débit, pas la liste des outils. Aucune « fonctionnalité premium réservée aux abonnés » — vous payez uniquement le passage des requêtes :

• Hobby — gratuit pour toujours, 60 requêtes/min ;
• Pro — 29 $/mois, 300 requêtes/min ;
• Scale — 199 $/mois, 1200 requêtes/min.

La clé gratuite Hobby est délivrée dès la connexion au dashboard, sans carte bancaire. Autrement dit, passer du mode local au hosted ne coûte pas un centime tant que 60 requêtes par minute vous suffisent — et c'est déjà nettement plus fiable que les lightservers publics.

Que faire si le serveur n'apparaît pas

Une connexion MCP tombe rarement en panne pour une raison compliquée — c'est presque toujours l'un de ces trois petits détails :

• Le serveur n'apparaît pas dans la liste des outils. Le client ne lit la config qu'au démarrage : après avoir modifié le fichier, relancez complètement Claude Desktop ou Cursor, ou redémarrez la session Codex. Dans Claude Code, vérifiez le statut avec la commande claude mcp list.
• Le serveur plante au lancement. En général, node/npx n'est pas dans le PATH — la commande npx -y @tonnode/mcp doit démarrer sans erreur dans un terminal classique. Si elle fonctionne dans le terminal mais pas depuis le client, indiquez le chemin absolu vers npx dans le champ command de la config.
• Les outils de lecture renvoient not ready ou un timeout. Ce n'est pas une erreur de votre setup, mais un lightserver public surchargé. Réessayez la requête ou, si cela se répète sous charge, passez à la clé hosted — débit dédié au lieu de la file d'attente commune.

Vérifiez aussi la validité de votre JSON et de votre TOML : une virgule en trop dans mcpServers ou des crochets mal fermés dans config.toml sont la cause la plus fréquente d'un serveur silencieusement ignoré par le client.

Mini-pratique : les outils que vous appellerez en premier

Quel que soit le client, la vérification finale est la même — un simple appel de lecture. Voici les prompts typiques et les outils qui se cachent derrière :

• « Quel est le seqno actuel de la masterchain ? » → get_masterchain_info. La tête du réseau, le meilleur moyen de vérifier que MCP est bien vivant.
• « Combien de GRAM sur le wallet UQ… ? » → get_balance. Le solde de la monnaie native.
• « Combien d'USDT sur cette adresse ? » → get_jetton_balance. Le jetton-wallet est calculé on-chain, pas besoin de connaître son adresse à l'avance.
• « Convertis l'adresse EQ… au format UQ » → parse_address. Conversion et validation des formats, hors ligne.

Ensuite, vous pouvez confier à l'agent de vraies tâches :

• « Vérifie get_account_state sur cette adresse et dis-moi si le contrat est déployé et de quand date la dernière transaction. »
• « Avec run_get_method, appelle get_wallet_data sur le jetton-wallet et décortique la réponse. » Comment appeler des get-méthodes read-only sans installer de SDK — voir l'article sur l'appel d'une get-méthode sans SDK.
• « Combien de décimales pour ce jetton ? Appelle get_jetton_info. » (USDT en a 6, la plupart des jettons en ont 9 ; les decimals servent à convertir correctement les unités raw.)

Un panorama complet de ce que MCP permet de faire sur TON est rassemblé dans le grand guide.

En résumé

Connecter un agent à TON, ce sont littéralement quatre lignes de JSON (ou une commande) dans la config de votre client. Le npx -y @tonnode/mcp local démarre sans installation et sans clé, avec l'ensemble complet des outils de lecture. Et quand vous buterez sur les limites des lightservers publics, vous basculez le transport vers l'endpoint hosted mcp.tonnode.io et insérez votre tn_live_…, sans changer une seule ligne de la logique de l'agent.

Récupérez la clé gratuite Hobby et collez-la dans votre config en une minute → tonnode.io/dashboard?plan=hobby. Pas de carte bancaire requise, et les 16 outils sont disponibles d'emblée. Envie de voir d'abord ce que le serveur sait faire ? Jetez un œil à la page des outils.