La cause la plus fréquente du « mon assistant ne voit pas mes données » n’est pas
un serveur cassé. C’est un client qui n’a jamais été redémarré après une
modification de la configuration. La plupart des clients MCP lisent leur
configuration au démarrage et plus jamais ensuite : un fichier que vous avez
modifié pendant que l’application était ouverte est un fichier qu’elle n’a pas
lu. Quittez-la complètement — sur macOS, fermer la fenêtre laisse le processus en
vie — puis rouvrez-la. Dans Claude Code, lancez /mcp plutôt que de redémarrer
le terminal.
Si cela ne suffit pas, la bonne question n’est pas « quel client j’utilise » mais « que se passe-t-il exactement ». Un serveur absent, un serveur qui se connecte sans exposer le moindre outil, des outils qui ne renvoient rien, et des outils qui n’échouent que lorsqu’ils essaient de modifier quelque chose sont quatre pannes différentes avec quatre correctifs différents — et le correctif ne dépend presque pas de l’application que vous utilisez. Chaque détail de cette page a été confronté à la documentation des éditeurs le 14 août 2026.
Avant de modifier quoi que ce soit, regardez ce que le client sait déjà. Chaque client a exactement un endroit qui répond à « ce serveur s’est-il connecté ? », et deviner depuis la fenêtre de conversation est la meilleure façon de passer une heure sur un problème que cet écran nomme en une seconde.
| Client | Où regarder | À quoi ressemble un serveur en bonne santé |
|---|---|---|
| Claude Code | claude mcp list ou le panneau /mcp |
✔ Connected |
| Claude Desktop | icône plus du champ de saisie → Connectors | le serveur est listé avec ses outils |
| Cursor | panneau Output (Cmd+Shift+U) → MCP Logs |
initialisation, aucune erreur de connexion |
| VS Code | MCP: List Servers dans la Command Palette | le serveur démarre, le journal Show Output est propre |
| Zed | Settings → AI → MCP Servers | point vert, infobulle Server is active |
Claude Code est le plus bavard de tous. claude mcp list affiche un état de
santé en face de chaque serveur — ✔ Connected, ! Needs authentication,
✘ Failed to connect, ⏸ Pending approval — et ajoute le détail de l’échec sur
cette même ligne ; claude mcp get <name> montre la même chose sur une ligne
Issue:, y compris le texte d’erreur renvoyé par le serveur lui-même.
Si l’écran d’état ne montre pas votre serveur, c’est que le client ne lit pas l’entrée que vous avez écrite. Trois causes couvrent la quasi-totalité des cas.
Le fichier n’est pas du JSON valide. Une virgule en trop ou une accolade manquante, et le client ignore le fichier entier — pas seulement l’entrée fautive — le plus souvent sans le dire. Collez le fichier dans un validateur JSON avant de soupçonner autre chose.
Vous avez modifié un autre fichier que celui que lit le client. Presque tous
les clients ont une configuration personnelle et une configuration de projet, et
éditer la mauvaise produit exactement ce symptôme. Cursor lit
~/.cursor/mcp.json globalement et .cursor/mcp.json à l’intérieur d’un
projet ; VS Code lit .vscode/mcp.json dans un espace de travail et un
mcp.json de profil utilisateur, ouvert avec MCP: Open User Configuration.
Claude Code a trois portées — local et utilisateur dans ~/.claude.json, projet
dans un .mcp.json à la racine du dépôt — et quand un même nom est défini dans
plusieurs, local l’emporte sur projet, qui l’emporte sur utilisateur. L’entrée
entière vient de la portée gagnante ; les champs ne sont pas fusionnés.
Le nom de la clé ne convient pas à ce client. La clé de premier niveau de
VS Code est servers, celle de Zed context_servers, et tous les autres
utilisent mcpServers. Un bloc mcpServers collé dans VS Code n’est pas une
erreur que l’éditeur signale — c’est simplement une clé qu’il ne lit pas. Le
détail client par client est dans
où se trouve la configuration MCP.
Un cas ressemble à un serveur absent sans en être un : dans Claude Code, un
serveur à portée de projet reste sur ⏸ Pending approval tant que vous n’avez
pas lancé claude en interactif dans ce dossier pour l’approuver, et les
approbations enregistrées dans le dépôt sont ignorées tant que vous n’avez pas
déclaré l’espace de travail comme fiable.
Quand rien n’a changé dans la configuration et que le serveur ne se connecte
plus, la configuration contient en général encore un chemin absolu vers un
programme qui n’est plus là. Mettre à jour une application dans un autre dossier,
la renommer ou la sortir du dossier Applications cassent le chemin alors que le
JSON a toujours l’air correct, et rien dans l’erreur du client ne pointe vers le
déplacement. Vérifiez la valeur de command face à la réalité avant toute autre
chose :
ls -l "/absolute/path/from/your/config"
La même famille de pannes touche les serveurs lancés par un gestionnaire de
versions. Si command vaut node, npx, python ou uv et que votre runtime
vient de nvm, pyenv ou asdf, le chemin existe dans votre terminal et n’existe pas
pour le client, parce que le client ne démarre pas de shell de connexion.
Remplacez le nom nu par le chemin absolu — which node vous le donne — ou faites
pointer command directement sur le binaire.
Un état vert avec une liste d’outils vide signifie que la poignée de main a
réussi et que tools/list n’a rien renvoyé d’utile. Deux choses produisent cela.
La première est un serveur qui déclare réellement un ensemble d’outils vide, ce que vous pouvez confirmer hors du client avec le MCP Inspector — l’interface de test de référence, qui se connecte directement à un serveur stdio ou Streamable HTTP et liste ce qu’il publie. Si l’Inspector voit des outils et pas votre client, la faute est dans la configuration du client.
La seconde est un plafond d’outils. VS Code limite une requête de chat à 128 outils activés et refuse la requête au-delà, seuil qu’une machine chargée atteint plus vite qu’on ne le croit ; le bouton Configure Tools de la vue Chat est l’endroit où désactiver des serveurs pour repasser sous la limite. Cursor permet de désactiver des serveurs un par un depuis le panneau Customize de la barre latérale, et un serveur désactivé n’est pas chargé et n’apparaît pas dans la conversation — à vérifier en premier, car un interrupteur basculé le mois dernier ressemble trait pour trait à un serveur en panne.
Les outils sont listés, l’assistant les appelle, et les résultats sont vides. Le transport va bien ; la question porte sur les données, pas sur la configuration. Vérifiez que la bibliothèque que lit le serveur est bien celle que vous avez en tête — le bon compte, le bon appareil, et du contenu réellement synchronisé sur cette machine plutôt que présent seulement sur une autre. Vérifiez ensuite les arguments de l’outil dans le journal du client : un assistant qui a deviné une plage de dates ou un filtre peut produire un résultat vide à partir d’une bibliothèque en parfait état.
Si les recherches aboutissent mais que chaque tentative de renommer, d’étiqueter ou de mettre à jour quelque chose échoue, ce n’est pas un problème de transport. Les serveurs séparent couramment les outils qui lisent de ceux qui modifient les données, et la moitié qui modifie porte souvent une exigence supplémentaire : une application en cours d’exécution, une session authentifiée, une permission que le client n’a pas reçue. Deux causes côté client méritent d’être écartées d’abord. Les outils qui modifient des données sont déclarés comme tels, donc le client demande avant de les exécuter — et une demande que vous avez ignorée se lit comme un échec dans la transcription. Et un serveur démarré avec un drapeau de lecture seule ne publie pas ces outils du tout, ce qui relève du choix de configuration et non de la panne.
Celle-ci est un bug du serveur plutôt que le vôtre, mais elle vaut d’être
reconnue parce que le message d’erreur induit en erreur. Sur stdio, le protocole
exige que la sortie standard ne transporte rien d’autre que des messages
JSON-RPC : un serveur qui écrit une bannière de version, une ligne « démarrage en
cours » ou un journal coloré sur stdout corrompt le flux, et le client échoue avec
une erreur d’analyse citant les premiers caractères de ce qui a été écrit —
Unexpected token 'S', "Starting s"... is not valid JSON. Le correctif appartient
à l’auteur du serveur : les lignes de journal vont sur stderr, que l’hôte capture
de toute façon.
L’environnement est l’autre piège au démarrage. Un serveur stdio n’hérite que
d’un sous-ensemble limité de variables d’environnement, qui dépend de la
plateforme — pas de votre profil de shell — et son répertoire de travail peut
être indéfini, en pratique / sur macOS. Passez ce dont le serveur a besoin par
la clé env de son entrée de configuration, et gardez tous les chemins absolus.
command existe, en absolu.Partir du haut coûte une minute. Commencer à l’étape sept, c’est transformer un problème de cinq secondes en après-midi entier.
Speak-Y embarque son serveur MCP dans l’application macOS, si bien que plusieurs
des pannes ci-dessus ne peuvent pas lui arriver : aucun paquet npm à installer,
aucun runtime à résoudre via nvm, aucun jeton qui expire. Celle qui peut arriver,
c’est le chemin périmé, et l’application le répare d’elle-même. Au lancement,
elle vérifie les configurations de Claude Code, Claude Desktop et Cursor et
réécrit la valeur de command là où elle pointe vers un ancien emplacement de
l’application — uniquement pour les entrées qui sont réellement les siennes,
reconnues au binaire de l’application et à l’argument --mcp, si bien qu’un
autre serveur portant le même nom est laissé tranquille. S’il faut le faire à la
main, Paramètres → Intégrations affiche Réinstaller en face de chaque
client détecté ; ensuite, redémarrez le client, ou lancez /mcp dans Claude
Code.
La séparation entre lecture et modification est l’autre symptôme à savoir
reconnaître. Chercher dans les enregistrements et lire les transcriptions, les
résumés et les action items fonctionne directement contre la bibliothèque
présente sur cette machine et n’exige rien d’autre en cours d’exécution. Les
outils qui organisent — tags, titres, noms d’intervenants, retranscription,
publication dans un canal d’équipe — passent par l’application en
marche : avec Speak-Y quitté, ils échouent tandis que la recherche continue de
fonctionner. Cette asymétrie est un diagnostic en soi : si la lecture marche et
pas la modification, démarrez l’application plutôt que de modifier une
configuration. Ajouter --read-only aux arguments du serveur retire complètement
les outils de modification de la vue du client — comportement voulu, pas
dysfonctionnement. Des résultats vides venant d’un serveur en bonne santé
signifient en général que l’enregistrement est encore sur un autre appareil : le
serveur lit ce disque et ne va pas chercher le reste.
Si vous êtes en train d’installer plutôt que de réparer, les guides client par client sont plus utiles que cette page : Claude Desktop et Claude Code pas à pas, et VS Code, Zed et Devin Desktop pour les éditeurs dont la forme de configuration diffère de celle de tous les autres.
La plupart des clients ne lisent la configuration MCP qu’au démarrage : un fichier écrit pendant que le client tournait n’a donc jamais été chargé. Quittez complètement l’application et rouvrez-la — sur macOS, fermer la fenêtre ne suffit pas — et dans Claude Code, lancez /mcp plutôt que de redémarrer le terminal.
Chaque client a un endroit unique qui répond à cette question. Claude Code : claude mcp list, qui affiche ✔ Connected, ! Needs authentication ou ✘ Failed to connect en face de chaque serveur. Claude Desktop : l’icône plus du champ de saisie, puis Connectors. VS Code : MCP: List Servers depuis la Command Palette. Cursor : le panneau Output avec MCP Logs sélectionné. Zed : Settings → AI → MCP Servers, où un point vert indique Server is active.
Dans ~/Library/Logs/Claude sur macOS et %APPDATA%\Claude\logs sur Windows. Suivez-les en direct avec tail -n 20 -F ~/Library/Logs/Claude/mcp*.log. Le fichier mcp.log contient les événements de connexion généraux, et mcp-server-NAME.log ce que ce serveur précis a écrit sur stderr.
Le client lance le processus lui-même, et non par votre shell de connexion. Il n’hérite pas de tout votre PATH, seulement d’un sous-ensemble limité de variables d’environnement qui dépend de la plateforme, et son répertoire de travail peut être indéfini. Utilisez un chemin absolu pour command, des chemins absolus dans les arguments, et passez les variables nécessaires explicitement par la clé env.
Presque toujours le chemin absolu de la configuration MCP, qui pointe vers l’ancien emplacement de l’application. Une réinstallation dans un autre dossier, un renommage ou un déplacement hors du dossier Applications cassent le chemin alors que la configuration a toujours l’air correcte. Relancez l’installation en un clic du client pour que le chemin soit réécrit.