MCP Troubleshooting: Fix Common Issues and Errors
Solve MCP connection, authentication, configuration, and tool call problems. This troubleshooting hub organizes solutions by symptom with step-by-step fixes for the most common issues.
Quick Diagnostic Checklist
Start here before diving into specific issues:
First Steps
- Check your config file: Is your MCP config valid JSON? Look for trailing commas, missing quotes, or typos
- Verify API key: Is your API key correctly copied with no trailing whitespace?
- Restart your client: Most config changes require a full restart (not just reload)
- Test connection: Can you reach api.corcava.com from your machine?
- Check permissions: Does your API key have the required access?
Troubleshooting by Symptom
Connection Issues
Problems connecting to the MCP server:
Connection Failed
Network, DNS, proxy, TLS, and firewall issues preventing connection.
Server Not Showing (Claude)
Fix when Corcava MCP doesn't appear in Claude Desktop.
Timeouts
Slow responses, large payloads, and timeout errors.
Authentication Issues
Problems with API keys and authorization:
401 Unauthorized
Missing Authorization header, wrong Bearer format, revoked keys.
403 Forbidden
Permission and access control issues, scope mismatches.
Configuration Issues
Problems with MCP config files:
Invalid Config JSON
JSON syntax errors, trailing commas, wrong nesting.
Cursor Changes Not Applied
Fix when Cursor doesn't apply config changes.
Windsurf Auth Headers
Windsurf connects but tool calls fail due to missing auth.
Windows Config Paths
Find and edit MCP config files on Windows.
macOS Config Paths
Find and edit MCP config files on macOS.
Tool Call Failures
MCP tools fail when you try to use them:
Tools Not Listed
Fix when tools/list returns empty or tools don't appear.
Tool Call Fails
Invalid arguments, wrong IDs, validation errors.
Performance Issues
Rate limits and performance problems:
429 Rate Limited
Rate limit errors and retry strategies.
Timeouts
Slow responses and timeout solutions.
Client-Specific Issues
Claude Desktop
Server not showing, config file location.
Cursor
Config changes not applied, reload issues.
Windsurf
Auth headers not sent, connection issues.
Continue
SSE stream failures, connection drops.
Additional Resources
- Complete Troubleshooting Index - All troubleshooting guides in one place
- MCP Debugging Checklist - Systematic debugging workflow
- Quickstart Guide - Start from scratch with proper setup
- Client Setup Guides - Client-specific configuration instructions