MCP en production : connecter Claude Code aux outils internes d'un client (retour de projet)

J'ai passé trois mois à câbler Claude Code sur les outils internes d'un client via le Model Context Protocol. Slack, PostgreSQL, un backoffice custom, un pipeline de déploiement. Sur le papier, MCP promet un branchement universel. En pratique, la distance entre un serveur MCP qui tourne dans un terminal et un service qui tient en production avec de l'auth, du rate limiting et des logs exploitables se mesure en semaines, pas en heures.

Ce retour de projet détaille ce qui a fonctionné, ce qui a cassé, et les choix d'architecture que je referais (ou pas) si c'était à refaire.

Ce que MCP résout (et ce que la spec ignore)

Avant MCP, connecter un agent IA à un outil externe revenait à écrire un wrapper custom par intégration. Un agent Claude n'utilisait pas les mêmes connecteurs qu'un assistant dans Cursor ou Copilot. Zéro portabilité, zéro standard.

MCP, créé par Anthropic, pose un protocole unique. L'agent joue le rôle de client, les outils deviennent des serveurs, et tout le monde parle JSON-RPC. Selon le blog d'Annei, l'écosystème comptait plus de 10 000 serveurs MCP actifs début 2026, avec 97 millions de téléchargements SDK par mois. Pour chaque outil courant (GitHub, Slack, PostgreSQL, Stripe, Notion), il existe un serveur open-source.

Pourquoi la promesse « tu branches une fois, ça marche partout » ne suffit pas ?

La spec MCP définit le quoi : format des messages, transports, lifecycle. Elle ne dit rien sur le comment de la production. D'après le guide de casys.ai, construire un serveur MCP qui répond à tools/list et tools/call prend une heure. Le rendre fiable en production prend trois semaines.

Ce delta couvre l'authentification (OAuth2, JWT, scopes), le rate limiting par IP ou par clé, la validation des schémas d'entrée, le contrôle de concurrence, les métriques Prometheus, les traces OpenTelemetry, et la gestion propre des signaux (SIGTERM, graceful shutdown). Ignorer un seul de ces points, c'est une bombe à retardement. Un serveur MCP sans validation de schéma, c'est une injection SQL qui attend son heure.

Ce constat rejoint ce que j'observe sur tous les projets où l'on intègre de l'IA sans dev senior dans la boucle : le POC fonctionne, la production explose.

Notre architecture : Claude Code + serveurs MCP custom

Le client utilisait un backoffice Node.js, une base PostgreSQL hébergée chez Neon, Slack pour les notifications internes, et un pipeline CI/CD maison sur GitHub Actions. L'objectif : permettre à Claude Code de lire et écrire dans ces quatre systèmes depuis le terminal d'un dev, sans quitter son IDE.

Comment structurer les serveurs MCP pour un environnement enterprise ?

J'ai opté pour une architecture hybride : stdio pour les outils locaux (filesystem, Git), Streamable HTTP pour les outils réseau partagés (Slack, PostgreSQL, backoffice). Le choix du transport n'est pas un détail. Selon la documentation de learn-prompting.fr, stdio reste le transport le plus simple (le client lance le serveur comme un sous-processus), mais il limite à un usage local, un seul client à la fois.

Pour le backoffice et la base PostgreSQL, j'ai conteneurisé chaque serveur MCP derrière un reverse proxy Traefik qui termine le TLS, route par nom d'hôte et applique le rate limiting. Le guide de Stéphane Robert détaille cette stack Docker Compose de façon exhaustive. J'ai repris 80 % de sa configuration en ajustant les health checks et les règles de rate limiting.

Chaque serveur exposait entre 3 et 8 outils. Le serveur PostgreSQL offrait query_read, query_write, list_tables, describe_table. Le serveur Slack exposait send_message, search_messages, list_channels. Le serveur backoffice exposait les CRUD sur les entités métier du client.

Le piège classique : tout exposer.

J'ai appris à démarrer en read-only, puis à ajouter les outils d'écriture après avoir construit la piste d'audit. Cette règle vient des équipes qui font tourner MCP à grande échelle, et elle m'a évité au moins deux incidents potentiels en phase de recette.

Quel rôle jouent les fichiers de contexte projet ?

Claude Code lit les fichiers CLAUDE.md, ARCHITECTURE.md et CONVENTIONS.md au lancement. Sur ce projet, j'ai structuré le CLAUDE.md pour décrire précisément chaque serveur MCP disponible, ses outils, et leurs contraintes d'usage. Ce système de mémoire projet fait la différence entre un agent qui devine et un agent qui exécute.

Sans cette couche de contexte, Claude Code appelait les outils MCP de façon erratique : requêtes SQL non bornées, messages Slack envoyés dans le mauvais canal, lectures de tables sans filtre. Avec un CLAUDE.md bien structuré, le taux d'appels pertinents est passé de ~60 % à 92 % sur nos métriques internes.

Les trois murs qu'on a pris en production

Faut-il confier des secrets à un serveur MCP ?

La sécurité est le sujet que tout le monde sous-estime. D'après Annei, 53 % des serveurs MCP déployés utilisent des secrets statiques : une API key dans un .env, stockée dans un pipeline CI/CD ou committée par accident. C'est la situation par défaut, et c'est un risque concret.

En juin 2025, Asana a déployé une intégration MCP. Un bug permettait à un client d'accéder aux données d'un autre. Cause : infrastructure partagée sans isolation des tokens par tenant. Patch d'urgence, incident public. Sur notre projet, j'ai imposé trois règles dès le jour 1 : rotation des tokens toutes les 24 h, allow-lists explicites par outil, et aucun credential que l'astreinte ne pouvait révoquer en moins de 60 secondes. Ce niveau de rigueur rejoint les recommandations de Gartner sur la sécurité des API qui place la gestion du cycle de vie des credentials parmi les trois priorités des architectures agent-to-tool.

Le OWASP LLM Top 10 le dit clairement : MCP ne résout pas le problème de sécurité du tool use par LLM, il le déplace. Un serveur MCP mal configuré qui expose un accès shell à un prompt compromis, c'est exactement le mode d'échec qu'il faut anticiper.

Comment gérer la fiabilité quand l'agent enchaîne les appels ?

Le deuxième mur, c'est la concurrence. Claude Code peut générer 4 à 5 appels MCP en rafale sur une seule réponse. Sans contrôle de concurrence côté serveur, la base PostgreSQL saturait en quelques minutes lors des sessions de refactoring lourd. J'ai ajouté un sémaphore configurable par serveur (max 3 appels simultanés sur le serveur PostgreSQL, 10 sur Slack) et un mécanisme de backpressure qui renvoie un code d'erreur explicite plutôt que de laisser l'agent tourner dans le vide.

Le troisième mur : les schémas d'outils qui dérivent entre versions du SDK. Une mise à jour du SDK MCP TypeScript a modifié la sémantique d'un champ optionnel dans tools/call, ce qui a cassé silencieusement notre serveur backoffice pendant deux jours. Leçon : épinglez vos versions SDK et testez chaque montée de version dans un environnement isolé.

Ce que je referais (et ce que je changerais)

Quand faut-il passer de stdio à Streamable HTTP ?

Ma règle après ce projet : si le serveur MCP est utilisé par un seul dev sur sa machine, stdio suffit. Dès qu'un deuxième utilisateur ou un pipeline CI doit y accéder, passez en Streamable HTTP derrière un reverse proxy. Le coût de mise en place (Traefik + Docker + TLS) se rentabilise dès la première semaine, parce que vous gagnez le rate limiting, les health checks et les logs centralisés gratuitement.

Ce que je changerais : j'aurais dû imposer un contrat d'interface formel pour chaque serveur MCP dès le premier sprint. On a perdu du temps à corriger des noms d'outils incohérents (get_user vs fetch_user, send_msg vs post_message) qui perturbaient Claude Code. Un fichier mcp-contract.yaml par serveur, versionné dans le repo, aurait évité cette dérive.

« Un serveur MCP en production, c'est un microservice. Si vous ne le traitez pas comme tel, il vous le rappellera un vendredi soir. »

Vincent Roye, mai 2026

Je referais le choix de Claude Code comme client MCP sans hésiter. La combinaison context plugins + fichiers CLAUDE.md + serveurs MCP bien scopés produit un workflow où l'agent comprend le périmètre métier, pas juste le code. C'est la différence entre un copilote qui auto-complète et un agent qui exécute des tâches métier. Et c'est exactement la direction que je pousse chez mes clients : ne pas juste utiliser l'IA, mais industrialiser un système de production logiciel autour d'elle.

Mon verdict : MCP tient en production, à condition de ne pas le traiter comme un simple plugin. Traitez chaque serveur comme un microservice, imposez des specs claires dès le sprint 0, et commencez read-only avant d'ouvrir les vannes. Pour une équipe de 2 à 5 devs avec un process structuré, le gain de productivité est réel. Pour une équipe qui branche MCP « pour voir », c'est un vecteur d'attaque de plus et un système distribué de plus à maintenir.