MCP Troubleshooting
Overview
Solutions to common issues when configuring and using the MCP server.
HTTP Errors
| Code | Cause | Solution |
|---|---|---|
| 401 | Invalid, expired, or missing API key | Regenerate an API key with the MCP preset from API Keys. |
| 403 | Missing scope on the API key | Verify that your key has the required scopes (mcp.read, mcp.write, etc.). |
| 404 | Disabled module or nonexistent resource | Verify that the module is enabled in your workspace (Knowledge Base, Agent, Governance). |
| 429 | Rate limit reached | Wait a few seconds before retrying. Limit: 1,000 requests/hour per key. |
JSON-RPC Error Codes
The MCP server uses the JSON-RPC 2.0 protocol. In case of a protocol error, the error.code field contains a standard code:
| Code | Meaning | Solution |
|---|---|---|
| -32600 | Invalid request | Verify that the body is a valid JSON-RPC 2.0 message (jsonrpc, method, id). |
| -32601 | Unknown method | Verify the method name (tools/call, tools/list, resources/list). |
| -32602 | Invalid parameters | Verify the types and required fields in the tool arguments. |
| -32603 | Internal error | Retry. If the issue persists, contact support. |
Client-Specific Issues
Claude Desktop
| Symptom | Solution |
|---|---|
| No MCP server visible | Verify the path to the claude_desktop_config.json file. Restart Claude Desktop. |
| Connection error | Verify the URL: https://api.ontologie-growthsystemes.com/api/mcp |
| Tools not loaded | Verify the X-API-Key and x-workspace-id headers. |
VS Code
| Symptom | Solution |
|---|---|
| MCP extension not found | Install the Copilot MCP extension from the VS Code marketplace. |
| Server disconnected | Verify settings.json. Reload the window (Ctrl+Shift+P > Reload Window). |
Cursor
| Symptom | Solution |
|---|---|
| MCP not available | Verify the Cursor version (MCP requires a recent version). |
| Authentication error | Verify the JSON format in Settings > MCP Servers. |
Claude Code
| Symptom | Solution |
|---|---|
claude mcp add fails | Verify that the Claude Code CLI is up to date (claude update). |
| Server unreachable | Test the connection: curl -I https://api.ontologie-growthsystemes.com/api/mcp |
n8n
| Symptom | Solution |
|---|---|
| Authentication refused | Use the composite format API_KEY:WORKSPACE_ID in the X-API-Key header. |
| Connection timeout | Verify that your n8n instance can access the platform URL. |
| Credential not recognized | The expected format is df_yourApiKey:your-workspace-id in a single Header Auth field. |
Missing Tools
If some tools do not appear in the tools/list response:
- Disabled module -- The Knowledge Base, Agent Studio, and Governance are optional modules. Enable them in the workspace settings.
- Insufficient scope -- Some tools require
mcp.write,mcp.workflow.execute,mcp.agent.execute, or thegovernance.*scopes. - Feature flag -- Some advanced features (Scenarios, Simulation, Templates) may be disabled in your environment.
Additional Common Issues
| Symptom | Cause | Solution |
|---|---|---|
| Governance/agent tools not visible | Module not enabled | Enable the module in the workspace settings. |
Timeout on workflow_execute | Long-running execution in synchronous mode | Pass async: true in the arguments for asynchronous execution. |
Missing outputSchema response | MCP client limitation | Some clients do not yet support outputSchema. This is not a server error. |
Diagnostic Tools
MCP Inspector
The MCP Inspector tool lets you test the connection and inspect the tools exposed by the server.
Test via curl
Send a JSON-RPC request to verify the server responds:
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"}'
Expected response: a JSON object containing the list of available tools.
Logs and Debug
Claude Desktop
MCP logs are in the Claude Desktop data directory:
- macOS:
~/Library/Logs/Claude/ - Windows:
%APPDATA%\Claude\logs\
For more details on MCP configuration in Claude Desktop, see the official MCP guide.
VS Code
Open the command palette (Ctrl+Shift+P) > Output > select the MCP channel in the dropdown menu.
Claude Code
Add the --verbose flag to see MCP exchanges:
claude --verbose
For more details on MCP configuration in Claude Code, see the official documentation.
Test the Connection
To verify that your MCP server is accessible:
curl -H "X-API-Key: df_VOTRE_CLE" \
-H "x-workspace-id: VOTRE_WORKSPACE_ID" \
https://api.ontologie-growthsystemes.com/api/mcp
Need Help?
Contact us: Support and Contact.