Comment nous avons unifié l'appel d'outils IA avec un seul changement de protocole

Il y a deux semaines, nous avons intégré un assistant IA dans sh0 qui pouvait interroger votre serveur, redémarrer vos applications et générer des fichiers de configuration. Cela fonctionnait. Mais l'architecture avait un problème que je savais devoir résoudre.

La boucle d'appel d'outils était complexe. Voici ce qui se passait chaque fois que Claude voulait vérifier l'état de votre serveur :

1. Vous envoyez un message à la passerelle à sh0.dev/api/ai/chat
2. La passerelle appelle Claude avec 9 définitions d'outils
3. Claude répond avec un bloc tool_use : « Je veux appeler get_server_status »
4. La passerelle émet un événement SSE tool_call vers le tableau de bord
5. Le JavaScript du tableau de bord intercepte l'événement, appelle l'API REST locale de sh0-core
6. Le tableau de bord renvoie le résultat à la passerelle en tant que tool_results
7. La passerelle rappelle Claude avec les résultats
8. Claude répond avec du texte
9. Les étapes 3 à 8 se répètent pour chaque appel d'outil dans la conversation

Neuf étapes. Trois allers-retours réseau. Les définitions d'outils dupliquées dans deux fichiers -- un sur la passerelle, un sur le tableau de bord. Le tableau de bord avait une fonction récursive runStreamLoop qui gérait l'intégralité de la boucle agentique côté client. Cela fonctionnait, mais c'était le genre d'architecture qui vous rend nerveux quand vous pensez aux cas limites.

Le protocole qui existait déjà

Pendant que nous construisions cela, sh0-core avait déjà un serveur MCP complet. Vingt outils, du JSON-RPC 2.0 correct, un transport Streamable HTTP, le scoping des clés API, des jetons de confirmation pour les opérations destructives. Nous l'avons construit sur trois phases, audité deux fois par phase. Il était prêt pour la production.

Et l'API de Claude avait quelque chose appelé le MCP Connector -- une fonctionnalité en bêta qui vous permet de dire à Claude « voici un serveur MCP, connecte-toi directement ».

La solution était évidente. Au lieu que la passerelle définisse les outils et que le tableau de bord les exécute, il suffisait de dire à Claude où se trouve le serveur MCP. Laisser Claude gérer la découverte et l'exécution des outils directement. L'intégralité de la boucle côté client disparaît.

À quoi ressemble le code

L'ancienne méthode :

typescriptconst response = await client.messages.create({
  model: modelString,
  max_tokens: 4096,
  system: systemPrompt,
  messages: apiMessages,
  tools: SH0_TOOLS,  // 9 définitions d'outils, maintenues manuellement
  stream: true,
});
// Puis : parser les blocs tool_use, émettre des événements SSE, attendre que le tableau de bord
// exécute, recevoir les résultats, rappeler Claude...

La nouvelle méthode :

typescriptconst response = await client.beta.messages.create({
  model: modelString,
  max_tokens: 4096,
  system: systemPrompt,
  messages: apiMessages,
  mcp_servers: [{
    type: 'url',
    url: `${instanceConfig.instanceUrl}/api/v1/mcp`,
    name: 'sh0',
    authorization_token: decryptedInstanceKey,
  }],
  tools: [
    { type: 'mcp_toolset', mcp_server_name: 'sh0' },
    ...GATEWAY_ONLY_TOOLS,
  ],
  betas: ['mcp-client-2025-11-20'],
  stream: true,
});
// Terminé. Claude découvre les outils via MCP, les appelle directement.
// Le flux contient du texte + des blocs informatifs mcp_tool_use/result.

Claude se connecte au serveur MCP, découvre les 20 outils via tools/list, et les appelle directement. Le flux de réponse inclut des blocs de contenu mcp_tool_use et mcp_tool_result que nous transmettons au tableau de bord à des fins d'affichage uniquement. Pas d'exécution. Pas d'allers-retours. Pas de boucle récursive.

Le tableau de bord affiche les étapes de traitement -- « Vérification de l'état du serveur », « Liste des applications » -- mais c'est purement cosmétique. Le vrai travail se fait entre Claude et le serveur MCP, deux machines qui communiquent entre elles pendant que l'utilisateur regarde le texte se diffuser.

Les décisions qui ont compté

Les outils gérés par la passerelle restent en tant qu'outils réguliers

Tout n'est pas un outil MCP. suggest_actions génère des pastilles d'actions de suivi. generate_config_file crée des cartes de configuration téléchargeables. Ce sont des fonctionnalités d'interface gérées par la passerelle elle-même -- elles ne touchent pas le serveur sh0-core.

Nous les gardons en tant que définitions d'outils Anthropic régulières aux côtés du toolset MCP. Quand Claude les appelle, la passerelle les traite et émet les événements SSE appropriés. Cela nécessite une boucle interne -- Claude s'arrête avec stop_reason: 'tool_use', nous fournissons les résultats de l'outil, Claude continue. Au maximum un aller-retour supplémentaire, et seulement quand Claude suggère des actions de suivi.

Le chemin legacy reste

Le MCP Connector ne fonctionne que quand l'instance sh0 est accessible via HTTPS depuis les serveurs d'Anthropic. Si vous exécutez sh0 sur une machine locale, derrière un pare-feu, ou sur un réseau que Claude ne peut pas atteindre, le chemin MCP échoue.

Quand il échoue, la passerelle émet un événement SSE mcp_fallback avec la raison, réinitialise son état, et exécute l'intégralité de la requête via le chemin legacy d'appel d'outils. Le tableau de bord gère les deux modes de manière transparente -- si des événements mcp_tool_use arrivent, il les affiche comme étapes de traitement ; si des événements tool_call arrivent à la place, la boucle agentique récursive se déclenche comme avant.

Pas d'échecs silencieux. L'utilisateur sait ce qui s'est passé et obtient quand même une réponse fonctionnelle.

La comptabilité des tokens est inchangée

La réponse du MCP Connector inclut l'utilisation totale de tokens exactement comme une réponse régulière. message_start a input_tokens, message_delta a output_tokens. Le surcoût des appels d'outils MCP -- les tokens que Claude utilise pour formater les requêtes et parser les réponses du serveur MCP -- est inclus dans ces compteurs automatiquement. La logique de déduction du portefeuille n'a pas changé du tout.

Ce que nous avons livré

L'implémentation touche les deux codebases :

sh0-website (passerelle) : - Nouveau modèle Prisma pour la configuration d'instance (stockage chiffré des clés API) - Nouvelle route API pour gérer la configuration d'instance - Endpoint de chat scindé en streamMcpPath() et streamLegacyPath() - Variante du prompt système pour le mode MCP - Définitions d'outils scindées : outils client, outils passerelle, combinés

Tableau de bord sh0-core : - Trois nouveaux handlers d'événements SSE (informatifs uniquement) - Labels et icônes d'outils MCP pour les 20 outils serveur - Correction de bug : les blocs tool_result sont maintenant correctement suivis dans l'historique de conversation

Le code de la boucle agentique du tableau de bord n'a pas été supprimé. Pas une seule ligne. Il ne s'exécute simplement jamais quand MCP est actif parce que les événements qui le déclenchent ne sont jamais émis. C'est le genre de simplification que je trouve le plus satisfaisant -- non pas supprimer du code, mais le rendre inutile grâce à une meilleure abstraction.

La leçon architecturale

L'ancienne architecture avait la bonne séparation des responsabilités mais le mauvais modèle d'exécution. La passerelle connaissait les outils. Le tableau de bord exécutait les outils. Claude orchestrait. Chaque couche faisait son travail, mais la chorégraphie entre elles était fragile.

Le MCP Connector effondre le modèle d'exécution. Claude et le serveur MCP gèrent l'intégralité du cycle de vie des outils. La passerelle devient un passe-plat. Le tableau de bord devient un afficheur. La complexité ne disparaît pas -- elle se déplace vers une frontière de protocole où elle a sa place.

C'est à cela que sert la conception de protocoles. Non pas pour simplifier les choses en théorie, mais pour déplacer la complexité là où elle peut être gérée par des machines au lieu d'être maintenue par des ingénieurs.

Vingt outils. Zéro exécution côté client. Un seul protocole.