Pourquoi mon MCP ne fonctionne-t-il pas ?

Lorsque vous utilisez le protocole MCP, plusieurs éléments communiquent ensemble : votre ordinateur (Node.js ou Python), le client (Claude Code), et le serveur (l'outil que vous essayez d'utiliser).

La très grande majorité des erreurs provient de l'une de ces 3 choses :

  • Un outil de base est manquant (comme Node.js).
  • Le fichier de configuration comporte une erreur de ponctuation (souvent une virgule manquante).
  • L'IA n'a pas les autorisations nécessaires pour accéder à vos données.
Information

Utilisez cette page comme une table d'orientation. Cherchez l'erreur qui vous bloque dans les catégories ci-dessous et cliquez dessus pour découvrir la solution étape par étape.

1. Problèmes d'Installation

Ces erreurs surviennent généralement lorsque vous essayez d'utiliser un serveur pour la toute première fois.

Node.js introuvable

L'erreur indique que la commande 'node' n'est pas reconnue par votre système.

Résoudre

npx non reconnu

Le terminal refuse de lancer npx pour installer un serveur.

Résoudre

Installation impossible

Le téléchargement du paquet échoue ou bloque à 0%.

Résoudre

2. Problèmes avec Claude Code

Ces erreurs apparaissent au moment où vous discutez avec l'IA et qu'elle tente de se servir d'un outil.

MCP non détecté

Claude ne voit pas le serveur que vous venez pourtant d'installer.

Résoudre

Permissions refusées

L'outil est détecté, mais Claude n'a pas le droit d'effectuer l'action demandée.

Résoudre

Configuration invalide

Le fichier .claude.json contient une erreur de syntaxe empêchant son chargement.

Résoudre

3. Erreurs spécifiques aux Serveurs

Ces erreurs concernent des problèmes de transport (STDIO) ou des configurations propres à certains serveurs.

Timeout

Le serveur met trop de temps à répondre et la connexion est coupée.

Résoudre

Déconnexion inattendue

L'erreur 'Connection closed by client' apparaît brusquement.

Résoudre

Erreurs Docker

Problèmes de permissions ou de conteneurs inactifs lors de l'appel au serveur Docker.

Résoudre

Gmail & Google Calendar

Problème d'authentification OAuth ou tokens invalides.

Résoudre

PostgreSQL

Connexion refusée ou base de données locale injoignable par le MCP.

Résoudre

Aller plus loin

Si votre problème ne figure pas dans cette liste, vous pourriez trouver la solution en consultant ces autres ressources :

Chapitre terminé