Dépanner les serveurs MCP dans Cursor

Les serveurs MCP étendent Cursor avec des outils externes, mais ce sont des processus indépendants dotés de leurs propres dépendances, et lorsqu'ils se comportent mal les symptômes peuvent être déroutants : un serveur affiché en rouge, une liste d'outils qui refuse de se rafraîchir ou un bouton de déconnexion qui semble ne rien faire. Ce guide vous donne une méthode systématique pour diagnostiquer les problèmes MCP dans Cursor, de la liste de tri rapide jusqu'aux correctifs spécifiques de chaque mode de défaillance courant, et vous montre comment valider n'importe quel serveur en dehors de l'IDE afin de déterminer si le problème vient du serveur ou de la connexion de Cursor à celui-ci.

Liste de tri rapide

Lorsqu'un serveur MCP se comporte mal, parcourez ce tableau de haut en bas. La plupart des problèmes se résolvent dans les trois premières lignes.

Symptôme	Première chose à vérifier	Correctif typique
Le serveur s'affiche en rouge ou ne démarre pas	Exécutez la commande du serveur manuellement dans un terminal	Corrigez le chemin de commande, un runtime manquant ou des variables d'environnement
Outils manquants ou obsolètes	Avez-vous modifié mcp.json sans redémarrer ?	Redémarrez Cursor ou rechargez la fenêtre
Le bouton de déconnexion ne fait rien	Le processus est-il réellement mort ?	Tuez le processus manuellement, puis reconnectez
Le serveur échoue et ne réessaie jamais	Cursor ne relance pas automatiquement après certains échecs	Désactivez puis réactivez le serveur, ou redémarrez
Les requêtes bloquent puis expirent	Le démarrage du serveur ou l'exécution des outils est trop lent	Préchargez les dépendances, augmentez le délai d'attente
Erreurs d'authentification	Token expiré ou variable d'environnement manquante	Rafraîchissez le token, corrigez l'environnement

Le serveur ne démarre pas

La défaillance MCP la plus courante est aussi la plus simple : la commande que Cursor utilise pour lancer le serveur ne fonctionne pas réellement. Cursor lance exactement la commande de votre mcp.json, avec l'environnement que vous lui avez fourni, et si elle échoue le serveur n'apparaît jamais.

Chemin de commande erroné

Vérifiez la commande exactement telle que Cursor l'exécuterait. Si mcp.json indique command": "npx" mais que votre PATH à l'intérieur du processus Cursor n'inclut pas npx, le lancement échoue. Sous Windows, c'est particulièrement fréquent car les applications graphiques héritent d'un PATH différent de celui de votre terminal.

{
  "mcpServers": {
    "filesystem": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\projects"]
    }
  }
}

Utiliser le chemin absolu vers l'exécutable est le correctif fiable sous Windows. Sur macOS et Linux, which npx vous donne le chemin absolu si la commande simple n'est pas trouvée.

npx ou uvx manquant

De nombreux serveurs MCP sont livrés sous forme de paquets npm ou Python et sont lancés via npx ou uvx. Si le runtime n'est pas installé, le serveur ne peut pas démarrer :

# Verify the runtimes exist
node --version    # Node 18+ for npx-based servers
npx --version
python --version
uvx --version     # install with: pip install uv

Si uvx est manquant, installez-le et redémarrez votre terminal et Cursor pour que le PATH mis à jour soit pris en compte.

Variables d'environnement erronées

Un serveur qui a besoin d'une clé API démarrera souvent puis se terminera immédiatement, ou démarrera et renverra des erreurs à chaque appel d'outil, lorsque son environnement est erroné. Lisez la documentation du serveur pour les noms exacts des variables, et rappelez-vous que Cursor ne transmet que ce que vous listez dans le bloc env :

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PAT}"
      }
    }
  }
}

Les outils ne se rechargent pas après modification de mcp.json

Vous modifiez mcp.json, l'enregistrez, ouvrez la liste des outils, et les nouveaux outils n'y sont pas. La configuration MCP est lue au démarrage du processus du serveur, donc les modifications ne se rechargent pas à chaud dans toutes les situations.

1. Enregistrez le fichier et confirmez qu'il s'agit de JSON valide. Une virgule finale rend tout le fichier non analysable et tous les serveurs peuvent échouer.
2. Redémarrez complètement Cursor, ou rechargez la fenêtre si votre version propose une option de rechargement dans la palette de commandes.
3. Ouvrez le panneau de paramètres MCP et confirmez que le serveur apparaît comme connecté.
4. Démarrez un nouveau chat. Une conversation existante peut avoir mis en cache l'ancienne liste d'outils, donc les nouveaux outils n'apparaissent que dans de nouvelles sessions.

Redémarrer vaut mieux que rafraîchir

Si désactiver puis réactiver le serveur dans le panneau MCP ne prend pas en compte vos modifications, faites un rechargement complet de la fenêtre ou redémarrez Cursor. mcp.json est lu au moment de la connexion, et un processus obsolète continue de servir sa liste d'outils d'origine quoi qu'indique désormais le fichier.

Problèmes de connexion et de nouvelles tentatives

Le bouton de déconnexion ne fait rien

L'action de déconnexion arrête le côté client de la connexion Cursor, mais avec les serveurs stdio le véritable processus enfant peut survivre s'il ne s'arrête pas proprement. Le résultat est un serveur qui semble encore à demi vivant et refuse une reconnexion propre. Lorsque le bouton semble ignoré :

# Find and kill a stubborn stdio MCP server process
# macOS / Linux:
ps aux | grep mcp
kill <PID>

# Windows PowerShell:
Get-Process | Where-Object { $_.ProcessName -like "*npx*" -or $_.ProcessName -like "*uvx*" }
Stop-Process -Id <PID> -Force

Une fois le processus disparu, reconnectez-vous depuis le panneau MCP. La connexion suivante démarre un nouveau processus avec votre configuration actuelle.

Aucune nouvelle tentative après une erreur de serveur

Si un serveur renvoie une erreur au démarrage ou pendant l'initialisation, Cursor ne continue généralement pas à réessayer en arrière-plan. Le serveur reste dans un état d'échec jusqu'à ce que vous interveniez. Les options de redémarrage manuel, par ordre de force croissante :

1. Désactivez puis réactivez le serveur dans le panneau de paramètres MCP.
2. Rechargez la fenêtre Cursor pour que tous les serveurs MCP se reconnectent.
3. Quittez complètement puis redémarrez Cursor.
4. Si le processus est bloqué, tuez-le comme indiqué ci-dessus puis reconnectez-vous.

Délais d'attente sur les serveurs lents

Les serveurs qui téléchargent des dépendances au premier lancement, ou les outils qui appellent des API externes lentes, peuvent dépasser le délai d'attente par défaut et signaler un échec qui ressemble à un serveur cassé. Le cas classique est un serveur basé sur npx à sa première invocation, lorsque npm récupère le paquet avant que quoi que ce soit puisse démarrer :

# Pre-warm an npx-based server so the first real connection is fast
npx -y @modelcontextprotocol/server-github --help

Pour les délais d'attente au niveau de l'hôte, de nombreux hôtes MCP, Cursor inclus, respectent les variables d'environnement conventionnelles de délai d'attente. Les définir avant de lancer Cursor donne plus de marge aux serveurs lents :

# macOS / Linux (add to your shell profile)
export MCP_TIMEOUT=30000        # server startup timeout in ms
export MCP_TOOL_TIMEOUT=120000  # individual tool call timeout in ms

Si un serveur est encore trop lent, hébergez-le différemment : exécutez-le comme un processus local persistant et connectez-vous via SSE ou HTTP au lieu de le lancer à chaque session.

Types de transport : stdio vs SSE/HTTP

Cursor prend en charge deux styles de transport MCP, et plusieurs étapes de dépannage diffèrent entre eux.

Aspect	stdio	SSE / HTTP
Mode d'exécution	Cursor lance le processus	Le serveur s'exécute séparément, Cursor se connecte à une URL
Clés de configuration	command, args, env	url (et les en-têtes là où c'est pris en charge)
Défaillances courantes	Chemin de commande erroné, runtime manquant	URL erronée, en-têtes d'authentification, problèmes CORS ou réseau
Comportement au redémarrage	La bascule reconnecte le processus	La reconnexion atteint le point de terminaison distant
Débogage	Exécutez la commande manuellement	Faites un curl sur le point de terminaison, consultez les logs du serveur

{
  "mcpServers": {
    "local-stdio-server": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "remote-http-server": {
      "url": "https://mcp.example.com/sse"
    }
  }
}

Pour les serveurs SSE et HTTP, vérifiez que le point de terminaison est joignable avant même de toucher à Cursor :

# A plain GET should return something, even if it is an auth error
curl -i https://mcp.example.com/sse

Un 401 ou 403 signifie que le transport est correct et que votre authentification est le problème. Un délai d'attente ou un refus de connexion signifie que le serveur est en panne ou que l'URL est erronée.

Variables d'environnement et secrets

mcp.json de projet vs global

Cursor lit la configuration MCP à deux endroits :

• Global : ~/.cursor/mcp.json (sous Windows : %USERPROFILE%\.cursor\mcp.json). S'applique à tous les projets. Placez-y les serveurs personnels : votre token GitHub, votre navigateur de base de données, vos outils de scraping.
• Projet : .cursor/mcp.json dans le dépôt. S'applique uniquement à ce projet et est partagé avec les coéquipiers lorsqu'il est commité. Placez-y les serveurs spécifiques au projet : un MCP de schéma pour la base de données de ce dépôt, une intégration d'outil de design utilisée par cette base de code.

Lorsqu'un serveur est défini aux deux endroits, attendez-vous à ce que la configuration du projet gouverne ce projet. Si des outils se dupliquent ou disparaissent, vérifiez les deux fichiers à la recherche d'une entrée portant le même nom.

Transmettre les secrets en toute sécurité

Cursor développe les placeholders ${VAR_NAME} dans le bloc env à partir de votre environnement, de sorte que les secrets peuvent vivre en dehors de mcp.json :

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${MY_DATABASE_URL}"
      }
    }
  }
}

# Set the real value in your shell profile, not in the JSON file
export MY_DATABASE_URL="postgresql://user:password@localhost:5432/appdb"

Ne commitez pas de secrets dans le dépôt

Le fichier .cursor/mcp.json au niveau du projet est un fichier ordinaire de votre dépôt. S'il contient une clé API en clair, chaque personne et chaque agent qui clone le dépôt obtient la clé. Utilisez l'expansion ${VAR} pour tout ce qui est sensible, et ajoutez mcp.json de projet à .gitignore s'il doit contenir des valeurs locales.

Lire les logs MCP

Lorsque le symptôme est peu clair, les logs nomment généralement le vrai problème. Cursor expose l'activité MCP via son infrastructure de sortie :

1. Ouvrez la palette de commandes et exécutez la commande pour afficher le panneau de sortie, ou utilisez le menu View.
2. Dans la liste déroulante des canaux du panneau de sortie, sélectionnez le canal MCP ou Cursor MCP logs.
3. Déclenchez l'action défaillante, puis lisez les entrées les plus récentes. Recherchez les erreurs de lancement, les codes de sortie non nuls et les traces de pile provenant de stderr du serveur.

Lignes de log typiques et leur signification :

[MCP] spawn npx ENOENT                 -> the runtime was not found on PATH
[MCP] server exited with code 1        -> the server crashed; run it manually for the real error
[MCP] initialize timed out             -> slow startup; pre-warm or raise the timeout
[MCP] tool call rejected: invalid args -> the model sent a bad schema; check the tool input

Le stderr côté serveur est transmis dans ces logs, donc une trace Python ou une exception de dépendance manquante venant du serveur lui-même apparaît généralement ici mot pour mot.

Valider un serveur de manière autonome

Le moyen le plus rapide de prouver si un problème vient de Cursor ou du serveur est d'exécuter le serveur sans Cursor.

Exécuter la commande manuellement

Copiez la command et les args de mcp.json et exécutez-les dans un terminal simple :

# Whatever your mcp.json launches, launch it yourself
npx -y @modelcontextprotocol/server-filesystem /tmp

Un serveur MCP stdio sain démarre et attend silencieusement une entrée JSON-RPC sur stdin. Si vous voyez au contraire une erreur de commande introuvable, un crash ou un échec d'installation de paquet, vous avez trouvé le problème et Cursor est innocent. Tapez quelques caractères et appuyez sur Entrée ; une réponse d'erreur de protocole brute est en fait bon signe, car elle prouve que le processus parle JSON-RPC.

Utiliser l'inspecteur MCP

L'inspecteur MCP officiel se connecte à un serveur, liste ses outils et vous permet de les appeler de manière interactive :

npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem /tmp

Cela ouvre une interface web locale où vous pouvez initialiser le serveur, lister les outils et en invoquer un avec des arguments écrits à la main. Si un outil fonctionne dans l'inspecteur mais pas dans Cursor, la différence est généralement l'environnement : des variables présentes dans votre terminal mais absentes dans le processus de Cursor, ou un répertoire de travail différent. Si l'outil échoue aussi dans l'inspecteur, corrigez d'abord le serveur ; rien de ce que vous changerez dans Cursor n'aidera.

mcp.json minimal fonctionnel

Utilisez ceci comme référence lorsque votre configuration a dérivé vers quelque chose qui ne démarre plus. Il montre un serveur stdio et un serveur distant, avec expansion d'environnement :

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/projects"
      ]
    },
    "remote-search": {
      "url": "https://mcp.example.com/sse",
      "env": {
        "API_TOKEN": "${MY_MCP_TOKEN}"
      }
    }
  }
}

Liste de vérification pour l'adapter à votre serveur :

1. Remplacez le nom du paquet et les arguments par ceux de la documentation du serveur.
2. Utilisez des chemins d'exécutable absolus sous Windows si la commande simple n'est pas trouvée.
3. Gardez les secrets sous forme de placeholders ${VAR} et définissez les valeurs réelles dans votre profil de shell.
4. Validez le JSON, puis redémarrez Cursor et confirmez que le serveur apparaît comme connecté avant d'ouvrir un chat.

Une mauvaise entrée peut casser tout le fichier

mcp.json est analysé comme un seul document JSON. Une simple virgule finale ou une valeur non mise entre guillemets rend tout le fichier invalide, et tous les serveurs qu'il contient peuvent échouer ensemble, y compris ceux qui fonctionnaient bien. Si plusieurs serveurs cassent d'un coup, soupçonnez la syntaxe du fichier avant de soupçonner chaque serveur.

Référence rapide

Objectif	Faire ceci
Serveur en rouge après le démarrage	Exécutez la commande manuellement ; corrigez le chemin, le runtime ou l'environnement
Nouveaux outils non affichés	Rechargez la fenêtre, puis démarrez un nouveau chat
Déconnexion sans réponse	Tuez le processus enfant, puis reconnectez
Échecs répétés, aucune nouvelle tentative	Désactivez puis réactivez le serveur, ou redémarrez Cursor
Délai d'attente au premier lancement	Préchargez le paquet, augmentez les variables d'environnement de délai d'attente
Soupçonner le serveur, pas Cursor	Validez avec une exécution manuelle ou l'inspecteur MCP
Soupçonner Cursor, pas le serveur	Comparez votre environnement à celui d'un terminal et lisez le canal de logs MCP