Claude Desktop MCP ne fonctionne pas ? Corrections pour la config et les serveurs HTTP

Votre serveur MCP fonctionnait hier. Aujourd’hui, Claude Desktop n’affiche aucun outil, une bannière « Server disconnected » ou rien du tout, et le seul indice est un message d’erreur vague qui ne mène nulle part. Cela arrive à presque tout le monde lorsqu’on branche un serveur local, et la cause est presque toujours l’une de ces cinq choses : un claude_desktop_config.json cassé, une commande que l’application ne trouve pas, un serveur qui écrit le mauvais texte sur stdout, un serveur HTTP ajouté de la mauvaise manière, ou une application qui n’a jamais été entièrement redémarrée.

Cet article passe en revue chaque panne dans l’ordre où vous devez les vérifier, avec le JSON, les chemins et les commandes exacts à coller. Procédez du haut vers le bas et arrêtez-vous dès que vos outils apparaissent. La plupart des corrections prennent moins de cinq minutes.

💡 Réponse rapide : quittez Claude Desktop depuis la barre d’état ou la barre de menus (pas seulement la fenêtre), passez votre configuration dans un validateur JSON, remplacez npx par son chemin absolu, et ajoutez les serveurs distants via Paramètres, Connecteurs plutôt que via le fichier de configuration. Cela suffit à résoudre la majorité des cas.

Vérifier d’abord les bases

Avant de toucher à la moindre ligne de JSON, écartez les causes banales. Elles font échouer plus de configurations que n’importe quel bug réel.

Quitter complètement Claude Desktop

Fermer la fenêtre ne signifie pas quitter. Sous Windows, l’application continue de tourner dans la zone de notification, et sous macOS elle reste active jusqu’à ce que vous appuyiez sur Cmd+Q. Claude Desktop ne lit sa configuration qu’au lancement : chaque modification effectuée pendant son exécution est donc ignorée.

Faites un clic droit sur l’icône de la zone de notification (ou utilisez la barre de menus), choisissez Quitter, attendez deux secondes, puis rouvrez l’application. Faites-le après chaque modification, même d’un seul caractère.

Ouvrir le bon fichier de configuration

Ne cherchez pas le fichier à la main. Ouvrez Paramètres, choisissez Développeur, puis cliquez sur Modifier la configuration. Cela ouvre le fichier exact que l’application lit. Les emplacements habituels ressemblent à ceci :

💡 Si vous modifiez un fichier et que rien ne change jamais, vous éditez peut-être une copie que l’application n’utilise pas. Certaines installations Windows empaquetées redirigent les données de l’application vers un autre dossier. Modifier la configuration ouvre toujours le bon.

Voici une configuration minimale qui fonctionne. Si celle-ci se charge et que la vôtre non, la différence entre les deux fichiers est votre bug.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"]
    }
  }
}

Copier le prompt

Lire les journaux avant de deviner

Chaque serveur local écrit son propre journal, nommé mcp-server-NAME.log, à côté d’un journal général mcp.log. Dans Paramètres, Développeur, chaque serveur indique aussi s’il fonctionne ou a échoué, ce qui vous permet de repérer d’un coup d’œil l’entrée à l’origine du problème.

Pour suivre les journaux en direct sous macOS :

tail -n 40 -F ~/Library/Logs/Claude/mcp*.log

Copier le prompt

Et sous Windows PowerShell :

Get-Content "$env:APPDATA\Claude\logs\mcp.log" -Tail 40 -Wait

Copier le prompt

Redémarrez l’application avec la fenêtre des journaux ouverte : l’erreur défile en général dans les premières secondes. Voici les lignes qu’il vaut la peine de reconnaître :

Corriger le JSON de configuration cassé

Claude Desktop ne pardonne pas les erreurs de syntaxe. Une seule virgule mal placée et tous les serveurs du fichier disparaissent, pas seulement celui que vous venez de modifier.

Les erreurs de syntaxe qui cassent tout

Vérifiez cette liste ligne par ligne :

• Virgules finales après la dernière propriété d’un objet ou d’un tableau.
• Commentaires. Le JSON n’en accepte aucun : les lignes // copiées depuis un tutoriel casseront le fichier.
• Guillemets typographiques. Les applications de messagerie et les traitements de texte transforment " en guillemets courbes qui se ressemblent mais échouent immédiatement.
• Une virgule manquante entre deux entrées de serveur.
• Un mauvais nom de niveau supérieur. Il doit être exactement mcpServers, avec ce S majuscule. Les variantes comme mcpservers ou servers sont ignorées sans message.
• Des nombres dans env. Les valeurs d’environnement doivent être des chaînes : écrivez "PORT": "8080", et non "PORT": 8080.
• Des sections supprimées. Si le fichier contenait déjà d’autres paramètres de niveau supérieur, conservez-les lorsque vous collez un nouveau bloc mcpServers.

Voici un exemple de fichier cassé :

{
  "mcpServers": {
    "notes": {
      "command": "node",
      // path to my server
      "args": ["C:\Users\Ana\notes-server\index.js"],
    }
  }
}

Copier le prompt

Et la version corrigée :

{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["C:\\Users\\Ana\\notes-server\\index.js"]
    }
  }
}

Copier le prompt

Le moyen le plus rapide de tout détecter d’un coup consiste à laisser un analyseur faire le travail. Python en fournit un :

python -m json.tool claude_desktop_config.json

Copier le prompt

S’il affiche votre fichier tel quel, la syntaxe est valide. S’il affiche une erreur avec un numéro de ligne, rendez-vous directement à cette ligne.

Chemins Windows et barres obliques inverses

La barre oblique inverse est le caractère d’échappement du JSON : C:\Users\Ana est donc invalide, car \U n’est pas un véritable échappement. Vous avez deux options sûres :

1. Doublez chaque barre oblique inverse : C:\\Users\\Ana\\notes-server\\index.js
2. Utilisez des barres obliques : C:/Users/Ana/notes-server/index.js

Windows accepte les barres obliques dans presque tous les cas, et elles sont bien moins sujettes aux erreurs. Les espaces dans les noms de dossiers sont acceptés dans une chaîne JSON, mais testez d’abord le chemin dans un terminal.

Corriger les erreurs de commande et de démarrage

La configuration est valide, l’application a redémarré, et le serveur échoue toujours. Le problème vient maintenant du processus lui-même.

Pourquoi spawn npx ENOENT se produit

ENOENT signifie « aucun fichier ou dossier de ce nom ». Claude Desktop lancé depuis le Dock ou le menu Démarrer ne lit pas votre profil de shell, il ne voit donc pas le PATH que vous avez dans un terminal. Si vous avez installé Node avec nvm, fnm, asdf ou Volta, les exécutables se trouvent dans un dossier que seul votre shell connaît. La commande fonctionne dans votre terminal et échoue dans l’application, ce qui explique la confusion.

Utiliser des chemins absolus pour Node

Demandez à votre terminal où se trouve réellement l’exécutable :

which npx     # macOS
where npx     # Windows

Copier le prompt

Collez ensuite le chemin complet dans command. Comme npx doit lui-même trouver node, ajoutez une entrée PATH dans env qui inclut le même dossier :

{
  "mcpServers": {
    "filesystem": {
      "command": "/Users/you/.nvm/versions/node/v22.11.0/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"],
      "env": {
        "PATH": "/Users/you/.nvm/versions/node/v22.11.0/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Copier le prompt

Exécutez aussi node --version. Beaucoup de serveurs lancés par npx ont besoin d’une version LTS récente de Node, et une ancienne installation système est une cause cachée classique.

L’enveloppe cmd de Windows

Sous Windows, npx est en réalité un fichier batch nommé npx.cmd, et le lancer directement peut échouer. Encapsulez-le dans cmd /c pour que le shell le résolve correctement :

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:/Users/Ana/Documents"]
    }
  }
}

Copier le prompt

Garder stdout propre

Ce point concerne surtout ceux qui écrivent leur propre serveur. Un serveur stdio communique avec Claude par des messages JSON-RPC sur stdout, et rien d’autre n’y est autorisé. Un seul console.log("server started") corrompt le flux, et l’application coupe la connexion avec une erreur Unexpected token.

💡 Certaines bibliothèques affichent une bannière ou un avertissement de dépréciation à l’importation. Si le journal contient du texte que vous n’avez jamais écrit, lancez le serveur dans un terminal et observez ce qui apparaît avant le premier message du protocole.

Corriger les serveurs HTTP et distants

Les serveurs HTTP sont la source de la plus grande confusion, car le fichier de configuration ressemble à l’endroit où les ajouter. Ce n’est pas le cas.

Le fichier de configuration ne gère que les serveurs locaux

Les entrées sous mcpServers lancent un programme sur votre machine et communiquent avec lui via stdin et stdout. Elles ne se connectent pas à une adresse web. Ajouter "url": "https://example.com/mcp" dans ce bloc est l’erreur HTTP la plus fréquente, car l’application n’a aucun moyen d’utiliser cette entrée.

Ajouter un connecteur personnalisé

Les serveurs distants passent par les Connecteurs. Les connecteurs personnalisés sont disponibles sur les offres Pro, Max, Team et Enterprise, et sur Team ou Enterprise, un propriétaire de l’organisation peut devoir ajouter le connecteur en premier.

1. Ouvrez Paramètres et choisissez Connecteurs.
2. Cliquez sur Ajouter un connecteur personnalisé.
3. Collez l’adresse HTTPS du point de terminaison du serveur, souvent terminée par /mcp.
4. Connectez-vous si le serveur demande OAuth.
5. Activez le connecteur depuis le menu des outils dans une nouvelle conversation.

Visez un point de terminaison Streamable HTTP. Un serveur qui ne parle que l’ancien transport SSE est une incompatibilité fréquente. Lorsque le connecteur échoue, ce tableau permet de restreindre le problème :

Un serveur lié à localhost est le coupable habituel lorsqu’un connecteur personnalisé refuse de se connecter, car cette adresse n’a pas le même sens selon l’endroit d’où part la requête.

Passer par un pont avec mcp-remote

Lorsque le serveur est privé, local ou nécessite un en-tête, le paquet mcp-remote joue le rôle de pont stdio. Claude le lance comme n’importe quel serveur local, et il transmet le trafic à votre point de terminaison HTTP :

{
  "mcpServers": {
    "my-remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://example.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Copier le prompt

Deux détails comptent ici. D’abord, écrivez l’en-tête sans espace après le deux-points et gardez la valeur réelle dans env. Sous Windows, les espaces à l’intérieur de args peuvent être altérés au démarrage de npx, et cette présentation contourne le problème. Ensuite, mcp-remote propose des options pour forcer un fonctionnement HTTP seul ou SSE seul : consultez son README lorsque la négociation par défaut choisit le mauvais transport. Tout ce qui précède reste valable : redémarrez complètement, utilisez des chemins absolus, lisez le journal.

Tester les serveurs en dehors de Claude

Lorsque vous ne savez pas si le problème vient du serveur ou de l’application, mettez l’application hors du circuit.

Lancer MCP Inspector

L’outil officiel MCP Inspector se connecte à un serveur et liste ses outils dans un onglet du navigateur :

npx @modelcontextprotocol/inspector node build/index.js

Copier le prompt

Pour un serveur HTTP, ouvrez l’Inspector, choisissez le type de transport correspondant, puis collez l’URL. Le résultat sépare nettement le problème :

• Les outils apparaissent dans l’Inspector mais pas dans Claude : le problème vient de votre configuration, du PATH ou du redémarrage.
• L’Inspector échoue aussi : le serveur est en cause, corrigez-le d’abord à cet endroit.

Tester HTTP avec curl

Pour un serveur Streamable HTTP, envoyez une vraie requête initialize et lisez le code de statut :

curl -i -X POST https://example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl-test","version":"0.0.1"}}}'

Copier le prompt

Utiliser les outils PicassoIA dans Claude

Une fois les connecteurs opérationnels, l’intérêt est de les utiliser. PicassoIA propose une connexion MCP pour que Claude crée des images et des clips pour vous dans une conversation. Cette connexion expose quatre modèles :

Les tâches de génération sont asynchrones. L’outil renvoie immédiatement un identifiant de prédiction, puis Claude vérifie l’état jusqu’à ce que la tâche réussisse ou échoue. Cette conception explique la plupart des signalements de type « ça ne répond plus » :

• Une tâche apparaît toujours comme en cours : demandez à Claude de vérifier la prédiction existante grâce à son identifiant. Soumettre à nouveau le même prompt ne fait que lancer une seconde tâche.
• Des échecs lorsque de nombreuses tâches tournent ensemble : un compte exécute jusqu’à cinq prédictions simultanément, partagées entre toutes les connexions. Restez donc à cinq ou moins.
• Outils absents après la connexion : activez le connecteur depuis le menu des outils et ouvrez une nouvelle conversation.
• Vous ne savez pas ce que votre offre permet : demandez à Claude de consulter votre compte, ou vérifiez la page des connexions MCP dans votre compte PicassoIA.

Utiliser Claude Sonnet 5 sur PicassoIA

Bloqué sur une configuration qui semble correcte mais échoue encore ? Confiez-la à un second regard. Claude Sonnet 5 fonctionne sur PicassoIA et est conçu pour le débogage de code, et il peut lire des captures d’écran de bannières d’erreur.

1. Ouvrez la page du modèle. Rendez-vous sur Claude Sonnet 5 sur PicassoIA.
2. Remplissez le prompt. Collez votre configuration, les 30 dernières lignes du journal, votre système d’exploitation, votre version de Node, et ce que vous attendiez. Supprimez d’abord tous les jetons.
3. Joignez une capture d’écran. Le champ image accepte une image de l’erreur. Augmentez max_image_resolution au-delà de sa valeur par défaut de 0,5 mégapixel si le texte paraît flou après redimensionnement.
4. Réglez l’effort. La valeur par défaut low est la plus rapide. Passez à high lorsque plusieurs serveurs interagissent ou que la cause n’est pas claire.
5. Ajoutez un prompt système. Par exemple : « Vous êtes un assistant de dépannage MCP. Renvoyez d’abord le JSON corrigé, puis une courte liste des causes. »
6. Générez et comparez. Confrontez la réponse à votre fichier, appliquez un seul changement à la fois, et redémarrez complètement l’application après chacun.

💡 Ne collez jamais de jetons réels dans une fenêtre de conversation. Remplacez-les par YOUR_TOKEN et ne remettez la vraie valeur que dans votre fichier local.

Pour les problèmes tenaces portant sur plusieurs fichiers, Claude Fable 5 et Claude Opus 4.7 sont également disponibles dans la même catégorie.

Créez votre première image dès aujourd’hui

Vos serveurs fonctionnent, les outils sont visibles, et la partie difficile est derrière vous. Consacrez maintenant dix minutes à la partie amusante. Ouvrez PicassoIA Image et rédigez un prompt pour une scène que vous accrocheriez vraiment au mur. Affinez-la avec PicassoIA Image Editor Pro, puis donnez-lui vie avec PicassoIA Video.

Essayez le même prompt dans trois styles, changez l’angle de prise de vue, faites passer l’éclairage de l’aube au crépuscule, et comparez. Le moyen le plus rapide de progresser consiste à multiplier les petites expériences et à garder celles qui vous surprennent. Lorsque vous voudrez plus d’options, parcourez tous les modèles sur picassoia.com/en/all-models et voyez ce qui convient à votre prochain projet sur Picasso IA.