Serveur MCP en 360 lignes sans SDK : cinq décisions qui ont empêché l'agent de casser les liens
Après une réponse « tool failed », l'agent devine : il relance l'appel, modifie les arguments ou s'excuse. L'auteur d'un service de liens raccourcis a écrit un serveur MCP de 360 lignes en Node.js, sans SDK, qui se contente de relayer l'API REST du service. Il renvoie désormais les erreurs comme un résultat ordinaire d'outil, et les opérations groupées avec un succès partiel. Conclusion : les réponses de l'API doivent aussi être conçues pour le modèle.
Traité par IA depuis Habr AI ; édité par Hamidun News
Connecter un agent à son propre service via le Model Context Protocol (MCP) n'est pas compliqué. Ce qui l'est, c'est de l'empêcher de s'égarer, d'enchaîner des requêtes inutiles et d'abîmer les données. Le développeur d'un service de liens raccourcis partage son expérience : son serveur MCP fait environ 360 lignes de Node.js pur, sans SDK ni dépendances, et presque chaque ligne est apparue après qu'un comportement inattendu de Claude Code ou de Cursor l'a obligé à la corriger. Le scénario est simple : l'agent rédige une newsletter ou des release notes, crée lui-même un lien avec des balises UTM, puis consulte les clics.
Un simple wrapper plutôt qu'une seconde copie de la logique
Le serveur ne contient aucune logique métier. Il reçoit l'appel d'un outil, interroge l'API REST existante avec une clé, puis renvoie la réponse. La validation, les limites et les contrôles de sécurité restent du côté de l'API.
Cela apporte trois avantages. Les règles vivent à un seul endroit : si l'on modifie une limite ou un contrôle d'URL, tous les clients MCP en bénéficient sans mise à jour du paquet. Le serveur se lance localement via npx et n'a besoin que d'une clé et de l'adresse de l'API. Enfin, il se teste facilement : il s'agit d'une simple correspondance « outil → requête HTTP ».
Le transport est lui aussi simple. Le serveur local échange avec le client via stdin et stdout, avec des messages JSON-RPC 2.0, une chaîne JSON par ligne. Par précaution, l'analyseur accepte aussi le format avec en-tête Content-Length, comme dans LSP. Deux points piègent facilement : stdin arrive par morceaux de taille quelconque, il faut donc un tampon qui conserve le reste non traité ; et stdout ne doit contenir que le protocole. Un seul console.log oublié suffit pour que le client désactive silencieusement le serveur. Le débogage doit être envoyé vers stderr.
Cinq décisions plus déterminantes que les autres
Les erreurs comme données. Si un échec de l'API est renvoyé comme erreur JSON-RPC, le client n'affiche souvent au modèle qu'un « tool failed ». Le modèle devine alors : il relance l'appel, change les arguments ou s'excuse auprès de l'utilisateur.
L'auteur renvoie désormais l'erreur comme un résultat ordinaire, avec le drapeau isError: true, et le texte entre dans le contexte. Les erreurs de protocole ne sont réservées qu'aux vraies pannes : méthode inconnue, outil inconnu, JSON invalide. Le texte d'erreur s'adresse au modèle : au lieu d'un simple « 401 », on lit « API_KEY is invalid.
Create a key at… ». Face à ce message, l'agent ne bombarde pas l'API de requêtes, mais indique à l'utilisateur où obtenir une clé.
Annotations des outils dangereux. Les outils portent des indications readOnlyHint, destructiveHint, idempotentHint et openWorldHint, selon lesquelles les clients décident quand demander une confirmation. La suppression et la désactivation d'un lien sont marquées comme destructives, la lecture de la liste et des statistiques comme en lecture seule. S'y ajoute la phrase « This cannot be undone » dans la description : le modèle demande alors lui-même confirmation à l'utilisateur. Mais il ne s'agit que d'indications, non d'une protection. Les véritables garde-fous sont les droits de la clé et les contrôles côté serveur.
Un traitement prévisible des URL. Les modèles aiment « corriger » les liens. Si l'utilisateur demande d'ajouter utm_source=newsletter alors que l'URL contient déjà utm_source=partner, qui l'emporte ? L'auteur a tranché : les paramètres existants ne sont pas écrasés, l'ancre #fragment est conservée, car quelqu'un a placé ces balises en connaissance de cause dans une campagne en cours. La règle est verrouillée par un test sur l'API et décrite dans la description de l'outil. La leçon générale : si le modèle peut transmettre un paramètre superflu ou contradictoire, le comportement du serveur doit être déterministe et documenté.
Succès partiel dans les lots. L'outil shorten_urls crée plusieurs liens d'un coup. Si l'un des dix ne passe pas la validation, une exception ferait croire au modèle que rien n'a abouti, et il relancerait tout, alors que neuf liens sont déjà créés. L'API répond donc par un objet contenant les tableaux created et errors, et le serveur le renvoie comme résultat ordinaire, même en cas d'erreur HTTP. Le modèle ne relance que les éléments en échec.
Les images comme des images. Un QR code encodé en base64 représente plusieurs kilo-octets de caractères dénués de sens dans le contexte, donc des tokens et des coûts superflus. MCP prévoit un type de contenu image : le client affiche l'image, accompagnée d'un court bloc de texte indiquant le type et la taille. Cela suffit pour que le modèle annonce « QR prêt, PNG, 4 Ko ».
Ce que l'auteur ferait différemment
La connexion tient en une commande : claude mcp add avec la clé et l'adresse via npx ; pour Cursor et Claude Desktop, la même configuration se décrit dans mcp.json. Ensuite, il suffit de demander à l'agent en langage courant.
L'auteur reconnaît aussi les limites de son approche. Les réponses de l'API auraient dû être conçues pour le modèle dès le départ : des causes d'erreur courtes et un succès partiel explicite sont utiles aussi aux intégrations classiques. Écrire le protocole à la main a du sens pour la compréhension, mais pour les ressources, les prompts et le transport HTTP, le SDK officiel fait gagner du temps. Enfin, il faut tester sur plusieurs clients à la fois : Claude Code, Cursor et MCP Inspector n'affichent pas les erreurs de la même façon et ne décident pas de la même manière quand demander une confirmation.
Le conseil pratique pour qui construit un MCP au-dessus de sa propre API : gardez la logique côté serveur, rédigez les erreurs comme des instructions destinées au modèle, signalez les opérations dangereuses et ne faites pas entrer dans le contexte ce que le modèle ne sait pas lire.
- 21 nov. 2026Huit outils open source pour agents IA : Browser Use en tête avec 121 000 étoiles
- 21 nov. 2026Parallel Search prend la première place du classement de 26 API de recherche pour agents IA avec 83 points
- 21 nov. 2026Text-to-cad : un agent d'IA dessine des pièces de robot à partir d'une description, le projet dépasse les 26 000 étoiles
- 21 nov. 2026La vidéo de Claude jouant à GTA 6 ressemble à un fake : une demi-heure de contrôle a épuisé la limite de 5 heures du forfait Pro
Questions clés sur cet article
Que sait-on sur Un simple wrapper plutôt qu'une seconde copie de la logique ?
Le serveur ne contient aucune logique métier. Il reçoit l'appel d'un outil, interroge l'API REST existante avec une clé, puis renvoie la réponse. La validation, les limites et les contrôles de sécurité restent du côté de l'API. Cela apporte trois avantages. Les règles vivent à un seul endroit : si l'on modifie une limite ou un contrôle d'URL, tous les clients MCP en bénéficient sans mise à jour du paquet. Le serveur se lance localement via npx et n'a besoin que d'une clé et de l'adresse de l'API.
Que sait-on sur Cinq décisions plus déterminantes que les autres ?
Les erreurs comme données. Si un échec de l'API est renvoyé comme erreur JSON-RPC, le client n'affiche souvent au modèle qu'un « tool failed ». Le modèle devine alors : il relance l'appel, change les arguments ou s'excuse auprès de l'utilisateur. L'auteur renvoie désormais l'erreur comme un résultat ordinaire, avec le drapeau isError: true, et le texte entre dans le contexte. Les erreurs de protocole ne sont réservées qu'aux vraies pannes : méthode inconnue, outil inconnu, JSON invalide.
Que sait-on sur Ce que l'auteur ferait différemment ?
La connexion tient en une commande : claude mcp add avec la clé et l'adresse via npx ; pour Cursor et Claude Desktop, la même configuration se décrit dans mcp.json. Ensuite, il suffit de demander à l'agent en langage courant. L'auteur reconnaît aussi les limites de son approche. Les réponses de l'API auraient dû être conçues pour le modèle dès le départ : des causes d'erreur courtes et un succès partiel explicite sont utiles aussi aux intégrations classiques.
Build & Ship Production AI Agents Without Boilerplate Code
Start your free 72-hour trial at Hamidun Academy (academy.hamidun.com) — interactive lessons on Claude Code & Cursor, live Tech Radar, and production agent templates.
L'essentiel de l'IA — une fois par semaine
Sept actus qui ont vraiment compté, choisies à la main. Sans bruit ni communiqués.
C'est fait ! Vérifiez votre boîte mail pour la confirmation.