Dépannage de la configuration MCP

Les problèmes de configuration MCP se regroupent autour de trois modes de défaillance : la résolution des commandes échoue silencieusement, les erreurs de syntaxe de configuration échouent silencieusement, et trop d’outils dégradent les performances de l’IA. Savoir où chercher et quels patterns appliquer résout la plupart des problèmes en moins de dix minutes.

Problèmes de PATH sur macOS

La défaillance la plus courante sur macOS. Les applications lancées depuis le Finder ou le Dock n’héritent pas du PATH de votre shell. Quand Claude Desktop ou un autre client IA GUI tente de lancer un serveur MCP avec une commande comme npx ou uvx, il ne trouve pas le binaire.

Le symptôme : le serveur n’apparaît pas dans votre client IA, et il n’y a pas de message d’erreur évident. Les logs (voir ci-dessous) afficheront quelque chose comme spawn npx ENOENT — « No such file or directory ».

La solution : utilisez des chemins absolus dans votre configuration MCP.

{
  "mcpServers": {
    "my-server": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "@antv/mcp-server-chart"]
    }
  }
}

Trouvez les chemins de vos binaires :

which npx    # → /opt/homebrew/bin/npx  (Homebrew sur Apple Silicon)
which uvx    # → /Users/vous/.local/bin/uvx
which node   # → /opt/homebrew/bin/node

Le préfixe Homebrew varie selon la puce : /opt/homebrew sur Apple Silicon, /usr/local sur Intel. Ne supposez pas — exécutez which pour confirmer.

Vous pouvez aussi configurer votre serveur MCP pour utiliser env afin de définir PATH explicitement :

{
  "mcpServers": {
    "my-server": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/full/path/to/server.js"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Pour Claude Code (utilisé depuis le terminal, qui hérite du PATH de votre shell), c’est moins souvent un problème. Les clients GUI ont besoin de chemins absolus.

Échecs silencieux de configuration JSON

Les fichiers de configuration MCP sont du JSON. JSON ne permet pas les virgules de fin. Il ne permet pas les commentaires. Une seule erreur de syntaxe fait que toute la configuration est silencieusement ignorée — le serveur ne se charge simplement pas, sans erreur visible pour l’utilisateur.

// JSON invalide — les commentaires ne sont pas autorisés
{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@antv/mcp-server-chart"],  // virgule de fin — aussi invalide
    }
  }
}

La solution : validez votre fichier de configuration avant de redémarrer le client.

# macOS / Linux
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool

# Ou utilisez un linter JSON
npx jsonlint ~/Library/Application\ Support/Claude/claude_desktop_config.json

Utilisez un éditeur de code avec la mise en évidence de la syntaxe JSON et le soulignage des erreurs (VS Code, Zed, etc.) comme éditeur par défaut pour ces fichiers. L’erreur de syntaxe sera soulignée avant que vous sauvegardiez.

Erreurs de syntaxe JSON courantes :

Virgule de fin après le dernier élément d’un objet ou d’un tableau
Commentaires (// ou /* */)
Guillemets simples au lieu de guillemets doubles
Caractères spéciaux non échappés dans les chaînes

Où trouver les logs de débogage

Claude Desktop écrit les logs de serveur MCP dans :

~/Library/Logs/Claude/mcp-server-[server-name].log

Ouvrez-les avec Console.app (recherchez « mcp ») ou depuis le terminal :

tail -f ~/Library/Logs/Claude/mcp-server-my-server.log

Les logs capturent à la fois stdout et stderr de votre processus serveur. C’est là que vous trouverez :

Les erreurs de lancement de processus (le spawn ENOENT pour les problèmes de PATH)
Les exceptions au démarrage du serveur
Les erreurs d’invocation des outils
Toute journalisation que votre serveur fait vers stderr

Pour Claude Code, exécutez le serveur MCP directement dans un terminal pour voir sa sortie :

uv run /path/to/server.py

C’est utile quand vous souhaitez voir la sortie côté serveur sans passer par les fichiers de log du client IA.

Nombre d’outils et performances de l’IA

La recherche sur l’utilisation des outils par l’IA montre une dégradation non linéaire du taux de succès à mesure que le nombre d’outils disponibles augmente. Avec 50 outils, l’IA atteint environ 31% de succès sur les tâches complexes. Avec 8 outils ciblés, les taux de succès atteignent 89%.

Le mécanisme est l’attention. Quand le modèle doit raisonner sur 50 outils, il dépense des tokens pour la sélection des outils qui pourraient aller à la résolution du problème réel. Il fait aussi plus d’erreurs sur quel outil appeler, générant des paramètres invalides ou choisissant le mauvais outil pour la tâche.

L’implication pratique pour la conception de serveurs MCP : si vous ne pouvez pas expliquer ce que chaque outil fait en une phrase, consolidez.

Signes que vous avez trop d’outils :

L’IA choisit fréquemment le mauvais outil pour une requête
Les descriptions des outils sont similaires entre elles (l’IA ne peut pas les distinguer)
Plusieurs outils font des variantes de la même chose (get_revenue, get_total_revenue, get_revenue_by_period)

Stratégies de consolidation :

Fusionnez les outils qui ne diffèrent que par des paramètres (ajoutez des paramètres optionnels au lieu d’outils séparés)
Supprimez les outils qui ne sont jamais utilisés en pratique
Divisez en serveurs MCP séparés par domaine — gardez le serveur de qualité de données séparé du serveur de catalogue de données, afin que chaque serveur ait un ensemble d’outils ciblé

Pour les équipes connectant plusieurs sources de données (BigQuery + dbt + GA4 + Looker), chaque source devrait être son propre serveur plutôt qu’un méga-serveur avec des outils pour tout. Le client IA charge les serveurs pertinents par conversation plutôt que d’avoir tous les outils disponibles simultanément. Voir MCP Tool Design Patterns pour les principes de conception qui évitent la prolifération des outils.

Exigences de redémarrage

Les serveurs MCP sont chargés au démarrage du client. Les modifications du code du serveur ou de la configuration nécessitent un redémarrage du client IA pour prendre effet.

Un piège de débogage courant : vous corrigez le code, relancez l’outil, obtenez la même erreur. L’ancien serveur est toujours en cours d’exécution. Quittez complètement et rouvrez le client (Cmd+Q, pas seulement fermer la fenêtre sur macOS).

Pour le développement actif avec Claude Code :

# Vérifiez que le serveur s'exécute avec vos modifications
claude mcp list
# Supprimez et ajoutez à nouveau le serveur après les modifications du code
claude mcp remove my-server
claude mcp add my-server -- uv run /path/to/server.py

L’Inspector MCP comme première étape de débogage

Avant de déboguer dans le vrai client IA, vérifiez que le serveur fonctionne en isolation :

npx @modelcontextprotocol/inspector uv run server.py

L’Inspector est un client de test basé sur navigateur. Il affiche tous les outils disponibles, vous permet de les invoquer avec des entrées de test et affiche les réponses brutes. Si un outil ne fonctionne pas dans l’Inspector, il ne fonctionnera pas dans Claude — mais l’Inspector vous donne une sortie d’erreur plus propre.

La note MCP Server Testing and Debugging couvre le workflow de test complet, y compris un piège critique : la journalisation vers stdout depuis votre serveur corrompra le protocole JSON-RPC. Utilisez stderr pour toute la journalisation côté serveur.