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. plus de 65 % 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, 80 % des incidents MCP se résolvent grâce à l'une de ces solutions.

Ce tableau couvre les cas rencontrés par plus de 90 % 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. 45 % des tickets de support 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/claude_desktop_config.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 environ 25 % des nouveaux utilisateurs MCP selon les forums communautaires (2025).

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 claude_desktop_config.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 représentent 20 % des problèmes MCP. 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. Voir les logs détaillés du dernier démarrage
claude mcp logs <nom-du-serveur>

# 4. Tester la connexion à un serveur spécifique
claude mcp test <nom-du-serveur>

# 5. Valider la configuration complète
claude config check

Claude Code v1.0.33 (février 2026) introduit la commande claude mcp test qui envoie un ping au serveur et vérifie que la liste d'outils est accessible. Le temps de réponse moyen attendu est de 150 ms pour un serveur local.

Pour un diagnostic plus approfondi, activez le mode verbose :

# Lancer Claude Code avec les logs MCP détaillés
CLAUDE_MCP_DEBUG=1 claude

Cette variable d'environnement affiche chaque message échangé entre Claude Code et les serveurs MCP. Le volume de logs peut atteindre 500 lignes par minute en utilisation normale - redirigez la sortie vers un fichier si nécessaire.

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 → claude mcp logs → claude mcp test résout 85 % des diagnostics en moins de 2 minutes.

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
time claude mcp test mon-serveur --tool list_files --params '{"path": "."}'

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.

les benchmarks Anthropic montrent qu'un serveur MCP bien optimisé répond en moins de 200 ms pour 95 % 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 : testez systématiquement vos serveurs MCP après chaque mise à jour avec claude mcp test 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), les logs via claude mcp logs, 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.