MCP Troubleshooting Index: Errors, Fixes, and Quick Links
Find solutions to common MCP issues quickly. This troubleshooting index organizes problems by symptom and provides direct links to detailed fix guides. Start with the quick checklist, then dive into specific solutions.
Quick Troubleshooting Checklist
Run through these checks first before diving into specific issues:
Quick Diagnostic Steps
- Check config file: Is your MCP config file valid JSON? See Config JSON Errors
- Verify API key: Is your API key active and correctly formatted? See 401 Unauthorized
- Test connection: Can you reach the MCP server endpoint? See Connection Failed
- Check tools list: Do tools appear in your client? See Tools Not Listed
- Restart client: Have you restarted your MCP client after config changes?
- Check permissions: Does your API key have the required permissions? See 403 Forbidden
Troubleshooting by Symptom
Connection Issues
Problems connecting to the MCP server:
Remote MCP Connection Failed
Diagnose network, DNS, proxy, TLS, and firewall issues preventing connection to remote MCP servers.
Claude Desktop: Server Not Showing
Fix issues when Corcava MCP doesn't appear in Claude Desktop. Config checks, JSON validation, restart steps.
Authentication Issues
Problems with API keys and authorization:
401 Unauthorized
Fix missing Authorization header, wrong Bearer format, revoked keys, and whitespace issues.
403 Forbidden
Resolve permissions and access control issues. Account-level access, scope mismatches, workspace validation.
Configuration Issues
Problems with MCP config files:
Config JSON Errors
Fix invalid JSON, schema mistakes, typos, trailing commas, wrong nesting, and header formatting issues.
Cursor: Changes Not Applied
Fix issues when Cursor doesn't apply config changes. Restart requirements, config file location, server verification.
Windsurf: Auth Headers Not Sent
Resolve cases where Windsurf connects but tool calls fail due to missing auth headers.
Windows Config Paths
Find and edit MCP config files on Windows. Common locations and safe editing tips.
macOS Config Paths
Find and edit MCP config files on macOS. Common locations and safe editing tips.
Tools Missing
MCP tools not appearing or available:
Tool Call Failures
Problems when calling MCP tools:
Performance Issues
Slow responses, timeouts, and rate limiting:
Timeouts and Slow Responses
Fix timeouts, long tool calls, and retry patterns. Mitigation steps: smaller queries, pagination, reducing parallel calls.
429 Rate Limited
Handle rate limiting. Causes (bursting, loops, large lists), safe retry/backoff, prompt patterns to reduce calls.
Client-Specific Issues
Problems specific to MCP clients:
Claude Desktop Issues
Server not showing up, config file location, JSON validation, restart steps.
Cursor Issues
Changes not applied after editing config, restart/reload requirements.
Windsurf Issues
Auth headers not being sent, connection issues.
Continue SSE Issues
Connection drops, streaming failures, retries. Config validation, network/proxy checks.
Still Need Help?
If you've tried the troubleshooting steps above and still have issues:
- Check the MCP Inspector guide for advanced debugging
- Review the MCP Security guide for authentication best practices
- See the Client Setup guides for client-specific configuration
- Contact support with specific error messages and diagnostic information
Get Your MCP Setup Working
Use these troubleshooting guides to fix connection, auth, and configuration issues