MCP : Model Context Protocol - Depannage

Le dépannage du Model Context Protocol dans Claude Code repose sur un diagnostic méthodique : vérifiez la configuration JSON, les logs serveur et la connectivité réseau. Ce guide vous donne les commandes, tableaux de résolution et procédures concrètes pour corriger les erreurs MCP les plus fréquentes en quelques minutes.

Le MCP (Model Context Protocol) est un protocole ouvert qui permet à Claude Code de se connecter à des serveurs externes pour accéder à des outils, des données et des contextes supplémentaires. la plupart des utilisateurs avancés de Claude Code exploitent au moins un serveur MCP dans leur workflow quotidien. Résoudre les problèmes liés au MCP est une compétence indispensable pour tout développeur qui utilise Claude Code en production.

le protocole MCP repose sur une architecture client-serveur standardisée où Claude Code agit comme client et se connecte à des serveurs via des transports stdio ou SSE. Si vous rencontrez des dysfonctionnements, consultez d'abord le guide fondamental du Model Context Protocol pour vérifier que votre compréhension du protocole est à jour.

Quels sont les problèmes MCP les plus fréquents et comment les résoudre ?

Voici le tableau de référence des 12 problèmes MCP les plus courants. Consultez ce tableau en premier avant toute investigation approfondie. En pratique, la majorité des incidents MCP se résolvent grâce à l'une de ces solutions.

Ce tableau couvre les cas rencontrés par plus de la grande majorité des utilisateurs. Pour les erreurs liées à d'autres aspects de Claude Code, consultez le guide général de dépannage.

À retenir : commencez toujours par identifier le symptôme exact dans ce tableau avant de creuser davantage.

Comment diagnostiquer un serveur MCP qui ne démarre pas ?

Un serveur MCP qui refuse de démarrer est le problème numéro un. La majorité des problèmes MCP concernent des erreurs de démarrage. Voici comment procéder méthodiquement.

Vérifiez d'abord que votre fichier de configuration existe et est syntaxiquement valide. Le fichier se trouve dans ~/.claude/ ou dans le répertoire de votre projet. Concrètement, lancez cette commande :

# Vérifier la syntaxe JSON de la configuration
cat ~/.claude/.mcp.json | jq.

Si jq renvoie une erreur, votre JSON est malformé. Les erreurs les plus courantes sont une virgule finale après le dernier élément d'un tableau ou une accolade manquante.

Testez ensuite le lancement manuel du serveur pour isoler le problème :

# Lancer le serveur MCP manuellement pour voir les erreurs
npx -y @modelcontextprotocol/server-filesystem /chemin/vers/dossier

Si le serveur démarre manuellement mais pas via Claude Code, le problème vient de la configuration. Comparez le chemin exact du binaire avec celui déclaré dans votre JSON. Si vous débutez avec MCP, le tutoriel pas à pas du Model Context Protocol vous guide dans la configuration initiale.

Node.js 22 LTS est la version recommandée en 2026 pour exécuter les serveurs MCP. Une version inférieure à Node.js 18 provoque des incompatibilités avec le protocole.

À retenir : lancez toujours le serveur manuellement en premier pour distinguer un problème de configuration d'un problème de code.

Comment vérifier la connectivité entre Claude Code et un serveur MCP ?

Une fois le serveur démarré, vous devez confirmer que Claude Code communique correctement avec lui. Le transport par défaut est stdio, mais certains serveurs utilisent SSE (Server-Sent Events) sur HTTP.

Exécutez la commande de diagnostic intégrée à Claude Code :

# Lister les serveurs MCP connectés et leur statut
claude mcp list

Cette commande affiche chaque serveur avec son statut : connected, disconnected ou error. En pratique, un statut disconnected avec un serveur configuré signifie que le processus a crashé silencieusement.

Pour les serveurs SSE, vérifiez la connectivité réseau :

# Tester la connexion SSE vers un serveur MCP distant
curl -N -H "Accept: text/event-stream" http://localhost:3001/sse

Vous devez recevoir un flux d'événements SSE. Si curl se ferme immédiatement, le serveur n'écoute pas sur ce port ou le protocole n'est pas SSE. Un temps de réponse supérieur à 5000 ms indique un problème de latence réseau.

Consultez le démarrage rapide MCP si vous configurez votre premier serveur et souhaitez un environnement fonctionnel en moins de 10 minutes.

À retenir : un serveur MCP qui apparaît dans claude mcp list mais affiche error nécessite une relance ou une correction de configuration.

Pourquoi les outils MCP n'apparaissent-ils pas dans Claude Code ?

Vous avez configuré un serveur MCP, il démarre sans erreur, mais les outils ne s'affichent pas. Ce problème touche de nombreux nouveaux utilisateurs MCP.

La cause la plus fréquente est un décalage entre le moment où vous modifiez la configuration et le moment où Claude Code la recharge. Redémarrez Claude Code complètement après chaque modification du fichier de configuration. Un simple rechargement de fenêtre ne suffit pas.

Vérifiez que le serveur expose bien ses outils via le protocole :

{
 "mcpServers": {
 "filesystem": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/vous/projets"],
 "timeout": 30000
 }
 }
}

Concrètement, si le bloc mcpServers est placé au mauvais niveau dans le JSON, Claude Code ignore la configuration sans message d'erreur. La clé mcpServers doit être à la racine du document JSON.

Un autre piège courant : le serveur MCP démarre mais retourne une liste d'outils vide. Vérifiez que la méthode tools/list du serveur fonctionne. Si vous utilisez un serveur custom, chaque outil doit être déclaré avec un schéma JSON valide comprenant name, description et inputSchema.

Pour les problèmes liés aux commandes slash qui ne fonctionnent plus après l'ajout d'un serveur MCP, consultez le guide des erreurs de commandes slash.

À retenir : après chaque modification de .mcp.json, redémarrez Claude Code intégralement - pas juste la fenêtre.

Comment résoudre les erreurs de permissions avec les serveurs MCP ?

Les erreurs de permissions sont un problème MCP courant. Elles se manifestent par des messages Permission denied, EACCES ou des outils qui refusent d'exécuter certaines actions.

Distinguez deux niveaux de permissions : les permissions système (fichiers, réseau) et les permissions Claude Code (politique de sécurité). Pour le premier niveau :

# Vérifier les permissions du binaire serveur
ls -la $(which npx)
# Rendre un serveur custom exécutable
chmod +x./mon-serveur-mcp.js

Pour le second niveau, Claude Code applique un système de permissions qui contrôle quelles actions les outils MCP peuvent exécuter. En pratique, un outil MCP qui tente de lire un fichier hors du répertoire autorisé sera bloqué.

Configurez les permissions dans votre fichier de projet .claude/settings.json :

{
 "permissions": {
 "allow": [
 "mcp__filesystem__read_file",
 "mcp__filesystem__list_directory"
 ],
 "deny": [
 "mcp__filesystem__write_file"
 ]
 }
}

Le format de permission MCP suit la convention mcp____. Vous trouverez le détail du système de sécurité dans le guide de dépannage des permissions. Ce point est critique : une permission mal configurée peut bloquer 100 % des appels MCP sans message d'erreur explicite.

les erreurs de permissions sont la première source de frustration chez les développeurs qui intègrent MCP dans un pipeline CI/CD. La formation Claude Code d'une journée inclut un lab dédié à la configuration des permissions MCP dans différents environnements, du poste développeur au serveur de production.

À retenir : vérifiez systématiquement les deux niveaux de permissions - système d'exploitation ET politique Claude Code.

Quelles commandes de diagnostic utiliser pour le dépannage MCP ?

Voici la liste complète des commandes de diagnostic que vous devez maîtriser. Exécutez-les dans l'ordre pour un diagnostic structuré en moins de 5 minutes.

# 1. Vérifier la version de Claude Code
claude --version

# 2. Lister les serveurs MCP et leur statut
claude mcp list

# 3. Supprimer et réajouter un serveur qui pose problème
claude mcp remove <nom-du-serveur>
claude mcp add <nom-du-serveur> -- <commande>

# 4. Vérifier la configuration dans le fichier.mcp.json
cat.mcp.json | jq.

La commande claude mcp list affiche le statut de chaque serveur configuré. Si un serveur est en erreur, supprimez-le et réajoutez-le avec claude mcp remove puis claude mcp add.

Pour un diagnostic plus approfondi, lancez Claude Code avec le flag --verbose pour obtenir des logs détaillés sur les connexions MCP.

Concrètement, les développeurs qui suivent la formation Développeur Augmenté par l'IA de 2 jours chez SFEIR apprennent à construire leurs propres outils de diagnostic MCP et à automatiser la détection d'anomalies dans leurs pipelines.

Si vous rencontrez des erreurs dans vos conversations Claude Code en général, le guide des erreurs courantes en conversation couvre les cas non spécifiques à MCP.

À retenir : la séquence claude mcp list puis claude mcp remove / claude mcp add résout la majorité des problèmes de serveur MCP.

Comment corriger les problèmes de performance d'un serveur MCP ?

Un serveur MCP lent dégrade directement l'expérience utilisateur dans Claude Code. Le temps de réponse maximal par défaut est de 30 000 ms (30 secondes). Au-delà, Claude Code coupe la connexion.

Mesurez d'abord les performances actuelles :

# Mesurer le temps de réponse d'un outil MCP
# Testez manuellement le serveur en le lançant directement
npx -y @modelcontextprotocol/server-filesystem /chemin/vers/dossier

Les causes de lenteur les plus fréquentes sont :

1. Initialisation coûteuse - le serveur charge des données volumineuses au démarrage. Solution : implémentez un chargement différé (lazy loading).
2. Appels réseau en cascade - chaque requête d'outil déclenche des appels API externes. Solution : ajoutez un cache local avec un TTL de 60 secondes.
3. Absence de pooling de connexions - chaque requête ouvre une nouvelle connexion. Solution : utilisez un pool de connexions HTTP.
4. Sérialisation JSON lourde - réponses de plus de 5 MB. Solution : paginez les résultats et limitez la taille à 1 MB par réponse.

Un serveur MCP bien optimisé répond en moins de 200 ms pour la plupart des requêtes. Un temps de réponse supérieur à 2000 ms est considéré comme problématique.

Pour les problèmes de performance liés à la configuration générale de Claude Code, la checklist MCP vous aide à vérifier chaque point d'optimisation.

À retenir : visez un temps de réponse MCP inférieur à 200 ms - au-delà de 2 secondes, l'expérience utilisateur se dégrade significativement.

Faut-il mettre à jour les serveurs MCP et comment procéder ?

Les serveurs MCP évoluent régulièrement. Une version obsolète peut provoquer des incompatibilités avec les nouvelles versions de Claude Code. En 2026, le protocole MCP est à la version 1.0 stable, mais les serveurs communautaires publient des mises à jour fréquentes.

Vérifiez la version de vos serveurs installés :

# Voir la version d'un serveur MCP installé via npm
npm list -g @modelcontextprotocol/server-filesystem
# Mettre à jour vers la dernière version
npm update -g @modelcontextprotocol/server-filesystem

la rétrocompatibilité est garantie au sein d'une version majeure. Un serveur écrit pour MCP 1.0 fonctionne avec tous les clients MCP 1.x. En revanche, un serveur MCP 0.x peut nécessiter une migration.

Pour approfondir les bonnes pratiques de maintenance et de mise à jour, consultez le guide des best practices avancées de dépannage. Vous y trouverez des stratégies de rollback en cas de régression.

À retenir : vérifiez systématiquement vos serveurs MCP après chaque mise à jour avec claude mcp list avant de les utiliser en production.

Peut-on déboguer un serveur MCP custom en développement ?

Le développement d'un serveur MCP custom est un cas d'usage avancé. Voici les techniques de débogage spécifiques à ce scénario. En pratique, le cycle de développement moyen d'un serveur MCP custom prend entre 2 et 5 jours.

Utilisez l'inspecteur MCP officiel pour visualiser les échanges en temps réel :

# Lancer l'inspecteur MCP (outil officiel Anthropic)
npx @modelcontextprotocol/inspector npx -y./mon-serveur-mcp.js

L'inspecteur ouvre une interface web sur le port 6274 qui affiche chaque message JSON échangé entre le client et votre serveur. Vous pouvez envoyer des requêtes manuelles pour tester chaque outil individuellement.

Voici les points de contrôle essentiels pour un serveur custom :

1. Vérifiez que la méthode initialize retourne les capabilities attendues
2. Validez que tools/list retourne un tableau d'outils avec des schémas conformes
3. Testez chaque outil individuellement avec des paramètres valides ET invalides
4. Gérez les erreurs proprement - retournez des codes d'erreur MCP standardisés (-32600 à -32603)
5. Implémentez le handler SIGTERM pour un arrêt propre

La formation Développeur Augmenté par l'IA – Avancé d'une journée chez SFEIR Institute inclut un module complet sur la création de serveurs MCP custom avec des exercices pratiques de débogage.

Pour les erreurs liées au système de mémoire qui interagit avec MCP, consultez le guide d'erreurs du système CLAUDE.md.

À retenir : l'inspecteur MCP (@modelcontextprotocol/inspector) est l'outil indispensable pour tout développement de serveur custom.

Quand faut-il contacter le support pour un problème MCP ?

Tous les problèmes MCP ne se résolvent pas en autonomie. Voici les critères pour escalader vers le support Anthropic ou la communauté.

Contactez le support Anthropic si :

• Le problème persiste après avoir suivi toutes les étapes de ce guide
• Vous observez un crash reproductible de Claude Code (pas du serveur MCP)
• Un serveur MCP officiel Anthropic retourne des erreurs de protocole
• Les logs montrent des erreurs internes Claude Code (préfixées INTERNAL_ERROR)

Dirigez-vous vers la communauté (GitHub Discussions, Discord MCP) si :

• Vous utilisez un serveur MCP communautaire ou custom
• Le problème est spécifique à votre environnement (OS, réseau, proxy)
• Vous cherchez des conseils d'architecture pour votre serveur MCP

Avant de contacter le support, préparez les informations suivantes : la sortie de claude --version, le contenu de votre fichier de configuration (sans données sensibles), le résultat de claude mcp list, et une description précise des étapes pour reproduire le problème. En pratique, un ticket bien documenté se résout 3 fois plus vite qu'un ticket incomplet.

Vous pouvez aussi consulter le guide général de dépannage Claude Code qui centralise les procédures d'escalade pour tous les types de problèmes.

À retenir : avant toute escalade, rassemblez version, configuration, logs et étapes de reproduction - cela divise le temps de résolution par 3.