Introduction

Le MCP (Model Context Protocol) est un protocole ouvert développé par Anthropic qui permet à Claude Code de se connecter à des outils externes et à des sources de données via une couche standardisée. Au lieu de travailler uniquement avec les fichiers d'un projet, une fois un serveur MCP intégré, Claude Code peut interroger des bases de données, appeler des API internes, lire de la documentation depuis Confluence ou exécuter des commandes système — le tout au sein d'une même session de travail.

Cette leçon vous guide à travers la connexion d'un véritable serveur MCP, puis résume les bonnes pratiques et les erreurs courantes lors de l'utilisation de Claude Code dans un projet réel.

Connexion d'un serveur MCP

Claude Code gère les serveurs MCP via la commande claude mcp. Il existe deux portées de configuration : locale (pour le projet courant uniquement, stockée dans .claude/settings.json) et globale (partagée entre tous les projets, stockée dans la configuration utilisateur).

Exemple d'ajout d'un serveur MCP fonctionnant via stdio — le type le plus courant lorsque le serveur est un processus exécuté sur votre machine :

claude mcp add my-db-tools -- npx -y @myorg/db-mcp-server

Après l'ajout, vérifiez que le serveur a bien été reconnu :

claude mcp list

Pour un serveur MCP fonctionnant via SSE (Server-Sent Events) — généralement utilisé lorsque le serveur est déjà déployé sur un endpoint HTTP :

claude mcp add --transport sse internal-api https://tools.internal.company.com/mcp

Lorsque le serveur nécessite des variables d'environnement (par exemple, des clés API, des chaînes de connexion), transmettez-les à l'aide du flag -e :

claude mcp add my-db-tools -e DB_URL=postgres://localhost/myapp -e DB_PASSWORD=secret -- npx -y @myorg/db-mcp-server

Une fois configuré, redémarrez Claude Code. Pendant une session, Claude détectera et utilisera automatiquement les outils exposés par le server — vous n'avez pas besoin de les appeler manuellement ; décrivez simplement votre besoin en langage naturel et Claude sélectionnera l'outil approprié.

Débogage des connexions MCP

Un échec de connexion MCP est généralement causé par l'un des quelques problèmes suivants, qui peuvent être vérifiés rapidement.

Le serveur MCP ne démarre pas : exécutez la commande du serveur directement en dehors de Claude pour voir l'erreur racine. Par exemple, si vous utilisez npx, exécutez-le manuellement dans le terminal pour confirmer que le package existe et ne signale aucune erreur de dépendance.

Claude ne voit pas l'outil : utilisez la commande suivante pour consulter l'état du serveur :

claude mcp get my-db-tools

Si le serveur signale un statut d'erreur, consultez les journaux détaillés en ajoutant une variable d'environnement lors de l'exécution de Claude :

MCP_DEBUG=1 claude

Syntaxe invalide dans settings.json : le fichier .claude/settings.json doit être un JSON valide. Les virgules traînantes ou les crochets manquants empêcheront le chargement de la configuration complète. Validez le fichier avant de l'exécuter :

cat .claude/settings.json | python3 -m json.tool

Les variables d'environnement ne sont pas transmises : notez que les variables fournies via le flag -e lors de l'ajout d'un serveur sont stockées en clair dans settings.json. Ne committez pas ce fichier s'il contient des secrets. Utilisez .gitignore pour exclure .claude/settings.json du dépôt.

Bonnes pratiques pour les projets réels

Les principes suivants sont tirés de l'expérience terrain, et non de la théorie.

Rédigez CLAUDE.md dès le départ et maintenez-le à jour. Ce fichier est la mémoire à long terme de Claude concernant le projet. Documentez clairement : comment exécuter les tests, les conventions de nommage, les fichiers qui ne doivent pas être modifiés et les décisions architecturales importantes. Claude lit ce fichier au début de chaque session — plus il est précis, moins Claude fera de suppositions erronées.

Utilisez git comme filet de sécurité. Avant chaque tâche majeure, assurez-vous que l'arbre de travail est propre. Après que Claude a apporté des modifications, relisez le diff avant de committer. Claude Code peut créer des commits automatiquement si vous le lui demandez, mais utilisez toujours des messages de commit explicites :

git diff --stat
git diff

Maintenez un cadrage de chaque tâche petit et clair. Au lieu de dire « refactoriser tout le module d'authentification », décomposez en « extraire la logique de validation du token dans une fonction séparée dans auth/token.js ». Un cadrage étroit aide Claude à rester concentré, facilite la revue et simplifie le retour en arrière en cas de problème.

Utilisez les sous-agents et /clear au bon moment. La fenêtre de contexte a des limites — lorsqu'une session couvre de nombreux fichiers et des tâches variées, utilisez /clear pour réinitialiser le contexte avant de démarrer une nouvelle tâche. Cela évite que Claude ne soit influencé par un contexte obsolète qui n'est plus pertinent.

Vérifiez les sorties à l'aide de tests automatisés, et pas seulement par une inspection visuelle. Après chaque modification de code, exécutez la suite de tests. Si le projet n'a pas encore de tests, c'est une bonne occasion de demander à Claude d'écrire les tests avant d'écrire l'implémentation.

Erreurs courantes à éviter

Assigner des tâches vagues et attendre des résultats précis. Claude fera de son mieux pour deviner — mais son devinement ne correspondra pas nécessairement à votre intention. Fournissez un contexte suffisant : quels fichiers sont impliqués, à quoi ressemble la sortie souhaitée et quelles contraintes doivent être respectées.

Laisser Claude modifier librement les fichiers sans contrôles de permission appropriés. Si vous utilisez le mode non supervisé (--dangerously-skip-permissions ou CI headless), limitez le périmètre via le fichier CLAUDE.md ou via des tâches clairement structurées. N'utilisez jamais ce flag dans un environnement de production.

Oublier que les serveurs MCP peuvent exposer des informations sensibles. Lorsqu'un serveur se connecte à une base de données ou à une API interne, Claude peut lire de vraies données. Limitez les autorisations du compte de service utilisé par le serveur MCP au minimum nécessaire.

Copier directement la sortie de Claude en production sans la lire. Le code généré par l'IA peut être logiquement correct mais faillible d'un point de vue sécuritaire, ou peut manquer des cas limites. La revue de code est obligatoire, et non optionnelle.

Résumé

Les serveurs MCP sont le pont qui permet à Claude Code d'aller au-delà des simples fichiers de code et d'interagir avec l'infrastructure réelle d'un projet. Une connexion correcte, un débogage systématique et l'utilisation du bon mode de transport sont les fondations d'une intégration stable. Au-delà de cela, des pratiques telles que la maintenance de CLAUDE.md, le maintien d'un cadrage de tâche restreint et la revue systématique avant le commit ne sont pas de simples formalités — ce sont les conditions qui rendent Claude Code réellement utile plutôt que de vous créer davantage de travail.