Depannage MCP

En bref

Solutions aux problemes courants lors de la configuration et l'utilisation du serveur MCP.

Erreurs HTTP

Code	Cause	Solution
401	Cle API invalide, expiree ou absente	Regenerez une cle API avec le preset MCP depuis Cles API.
403	Scope manquant sur la cle API	Verifiez que votre cle possede les scopes requis (mcp.read, mcp.write, etc.).
404	Module desactive ou ressource inexistante	Verifiez que le module est active dans votre workspace (Base de connaissances, Agent, Gouvernance).
429	Limite de debit atteinte	Attendez quelques secondes avant de reessayer. Limite : 1000 requetes/heure par cle.

Codes erreur JSON-RPC

Le serveur MCP utilise le protocole JSON-RPC 2.0. En cas d'erreur protocolaire, le champ error.code contient un code standard :

Code	Signification	Solution
-32600	Requete invalide	Verifiez que le corps est un JSON-RPC 2.0 valide (jsonrpc, method, id).
-32601	Methode inconnue	Verifiez le nom de la methode (tools/call, tools/list, resources/list).
-32602	Parametres invalides	Verifiez les types et champs requis dans les arguments de l'outil.
-32603	Erreur interne	Reessayez. Si le probleme persiste, contactez le support.

Problemes par client

Claude Desktop

Symptome	Solution
Aucun serveur MCP visible	Verifiez le chemin du fichier claude_desktop_config.json. Redemarrez Claude Desktop.
Erreur de connexion	Verifiez l'URL : https://api.ontologie-growthsystemes.com/api/mcp
Outils non charges	Verifiez les headers X-API-Key et x-workspace-id.

VS Code

Symptome	Solution
Extension MCP introuvable	Installez l'extension Copilot MCP depuis le marketplace VS Code.
Serveur deconnecte	Verifiez settings.json. Rechargez la fenetre (Ctrl+Shift+P > Reload Window).

Cursor

Symptome	Solution
MCP non disponible	Verifiez la version de Cursor (MCP necessite une version recente).
Erreur d'authentification	Verifiez le format JSON dans Settings > MCP Servers.

Claude Code

Symptome	Solution
claude mcp add echoue	Verifiez que le CLI Claude Code est a jour (claude update).
Serveur inaccessible	Testez la connexion : curl -I https://api.ontologie-growthsystemes.com/api/mcp

n8n

Symptome	Solution
Authentification refusee	Utilisez le format composite CLE_API:WORKSPACE_ID dans le header X-API-Key.
Timeout lors de la connexion	Verifiez que votre instance n8n peut acceder a l'URL de la plateforme.
Credential non reconnu	Le format attendu est df_votreCleApi:votre-workspace-id dans un seul champ Header Auth.

Outils manquants

Si certains outils n'apparaissent pas dans la liste tools/list :

1. Module desactive — La Base de connaissances, l'Agent Studio et la Gouvernance sont des modules optionnels. Activez-les dans les parametres du workspace.
2. Scope insuffisant — Certains outils necessitent mcp.write, mcp.workflow.execute, mcp.agent.execute ou les scopes governance.*.
3. Feature flag — Certaines fonctionnalites avancees (Scenarios, Simulation, Templates) peuvent etre desactivees sur votre environnement.

Problemes courants supplementaires

Symptome	Cause	Solution
Outils governance/agent non visibles	Module non active	Activez le module dans les parametres du workspace.
Timeout sur workflow_execute	Execution longue en mode synchrone	Passez async: true dans les arguments pour une execution asynchrone.
Reponse outputSchema absente	Limitation du client MCP	Certains clients ne supportent pas encore outputSchema. Ce n'est pas une erreur serveur.

Outils de diagnostic

MCP Inspector

L'outil MCP Inspector permet de tester la connexion et d'inspecter les outils exposes par le serveur.

Test via curl

Envoyez une requete JSON-RPC pour verifier que le serveur repond :

curl -X POST https://api.ontologie-growthsystemes.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: df_VOTRE_CLE" \
  -H "x-workspace-id: VOTRE_WORKSPACE_ID" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Reponse attendue : un objet JSON contenant la liste des outils disponibles.

Logs et debug

Claude Desktop

Les logs MCP sont dans le dossier de donnees de Claude Desktop :

• macOS : ~/Library/Logs/Claude/
• Windows : %APPDATA%\Claude\logs\

Pour plus de details sur la configuration MCP dans Claude Desktop, consultez le guide officiel MCP.

VS Code

Ouvrez la palette de commandes (Ctrl+Shift+P) > Output > selectionnez le canal MCP dans le menu deroulant.

Claude Code

Ajoutez le flag --verbose pour voir les echanges MCP :

claude --verbose

Pour plus de details sur la configuration MCP dans Claude Code, consultez la documentation officielle.

Tester la connexion

Pour verifier que votre serveur MCP est accessible :

curl -H "X-API-Key: df_VOTRE_CLE" \
     -H "x-workspace-id: VOTRE_WORKSPACE_ID" \
     https://api.ontologie-growthsystemes.com/api/mcp

Besoin d'aide ?

Ecrivez-nous : Support et contact.