L'informatique n'est jamais parfaite. Parfois, tu configures un serveur MCP, tu demandes à Claude de l'utiliser, et rien ne se passe. Ou pire, une grosse ligne d'erreur rouge envahit ton écran.

Ne panique pas. 95% des erreurs MCP proviennent de fautes de frappe ou d'oublis très basiques. Voici comment les résoudre.

1. Le diagnostic rapide

Avant d'essayer de réparer quoi que ce soit, il faut identifier le malade.

Si ton serveur est marqué comme actif, alors le problème vient d'ailleurs. S'il est marqué en erreur, c'est que l'installation ou la configuration a échoué. Voici les pannes les plus courantes.

2. L'erreur classique : Le mauvais chemin

Symptôme : Le serveur est introuvable ou affiche "command not found".

Cause : Tu as indiqué à Claude que l'outil se trouvait dans le tiroir du haut, mais il est en fait dans la cave.

Résolution : Vérifie scrupuleusement la commande d'installation. Si tu utilises un fichier local, assure-toi que le chemin absolu (comme C:/Projets/mon-serveur/index.js) est correct, sans fautes de frappe.

Attention

Attention aux espaces dans les noms de dossiers sur Windows ! Si ton projet s'appelle "Mon Projet", l'ordinateur lira "Mon" et s'arrêtera. Utilise toujours des tirets : "mon-projet".

3. L'erreur de moteur : Le programme introuvable

Symptôme : Le terminal affiche "npx is not recognized" ou "Node.js absent".

Cause : Ton serveur a besoin du moteur Node.js pour tourner, mais il n'est pas (ou mal) installé sur ton ordinateur.

Résolution : Télécharge et réinstalle la version LTS de Node.js depuis leur site officiel. N'oublie pas de redémarrer ton ordinateur pour que le système prenne en compte le nouveau moteur.

4. L'erreur de porte d'entrée : La clé d'API manquante

Symptôme : Le serveur démarre, mais refuse de travailler en affichant "Unauthorized" ou "Permission denied".

Cause : Tu essaies d'accéder à un service privé (comme GitHub, Slack ou Notion) sans lui avoir donné ta carte d'identité (ta clé secrète, ou API key).

Résolution : La plupart des serveurs de communication exigent d'ajouter un mot de passe spécial dans ta commande d'installation (par exemple : mcp add github npx -y @modelcontextprotocol/server-github --env GITHUB_TOKEN=ton_mot_de_passe).

5. La checklist de sauvetage

Si rien ne marche, coche ces cases l'une après l'autre :

Bonnes pratiques
  • J'ai redémarré Claude Code (il faut parfois lui forcer la main).
  • J'ai tapé node -v et npm -v dans mon terminal classique pour vérifier que le moteur tourne.
  • J'ai bien recopié le nom exact du package npm (une faute de frappe est si vite arrivée).
  • J'ai utilisé mcp list pour vérifier que le serveur n'est pas enregistré en double avec des paramètres contradictoires.

6. FAQ

Claude Code affiche généralement une erreur rouge dans le terminal quand un serveur crash. Si tu veux plus de détails, tu peux utiliser un outil d'inspection MCP dédié, mais c'est réservé aux développeurs très avancés.
Si c'est la première fois, oui, car ton ordinateur doit télécharger le serveur depuis internet via npm. Les lancements suivants doivent être instantanés.
Oui, très facilement. Tape simplement la commande 'mcp remove nom-du-serveur' dans Claude Code. Cela nettoiera la configuration proprement.

Et voilà ! Tu as survécu à la partie la plus technique de l'écosystème. Tu sais désormais comment fonctionne un MCP, comment l'installer, le créer et le réparer. Nous allons maintenant passer à un sujet tout aussi passionnant : l'intégration de Claude Code avec ton outil de sauvegarde Git.

Chapitre terminé