MCP Connection Failed: Complete Troubleshooting Guide
Fix connection refused, timeout, and server errors for Claude Desktop, Cursor, VS Code, and Windsurf. Step-by-step solutions for all common MCP connection issues.
Quick Fix (TL;DR)
90% of MCP connection errors are solved by: 1) Restarting your IDE completely, 2) Verifying config file location is correct for your IDE, 3) Using npx/uvx commands instead of manual server paths, 4) Checking environment variables are set. If still failing, check server logs in your IDE's output panel.
Common MCP Connection Errors
Connection Refused (ECONNREFUSED)
Causes:
- MCP server not running or crashed
- Incorrect port number in configuration
- Firewall blocking the connection
- Server started after IDE
Solutions:
- Restart your IDE (Claude Desktop/Cursor/VS Code)
- Check server logs for crash errors
- Verify port numbers match in config
- Disable firewall temporarily to test
Timeout Error (Connection Timeout)
Causes:
- Server taking too long to start
- Heavy computation blocking startup
- Network latency issues
- Missing dependencies not installed
Solutions:
- Increase timeout in IDE settings (default: 30s)
- Check MCP server logs for slow operations
- Install all required npm/pip packages
- Use npx/uvx to auto-install dependencies
MCP Not Showing in IDE
Causes:
- Configuration file in wrong location
- Invalid JSON syntax in config
- IDE didn't reload after config change
- MCP server name mismatch
Solutions:
- Verify config file location (see IDE-specific guides below)
- Validate JSON with online JSON validator
- Restart IDE completely (not just reload window)
- Check server name matches exactly
Authentication Failed
Causes:
- Missing or invalid API key
- API key not set as environment variable
- API key expired or revoked
- Incorrect permission scopes
Solutions:
- Set API keys in environment variables
- Regenerate API key from provider dashboard
- Check API key has required permissions
- Use .env file and restart IDE
Server Crashed or Not Responding
Causes:
- Unhandled exception in MCP server code
- Out of memory
- Dependency conflicts
- Node.js/Python version mismatch
Solutions:
- Check server logs in IDE console/output panel
- Update Node.js to v18+ or Python to 3.10+
- Clear npm cache: npm cache clean --force
- Reinstall dependencies: rm -rf node_modules && npm install
IDE-Specific Troubleshooting
Claude Desktop
Common Issues:
- Config file doesn't exist → Create it manually
- Invalid JSON → Use JSON validator
- Server path incorrect → Use absolute paths
- Node.js not in PATH → Restart after installing Node.js
Cursor
Common Issues:
- Wrong config location → Check .cursor folder exists
- Server not auto-starting → Use npx command
- Port conflicts → Change port in config
- Extension conflicts → Disable other MCP extensions
VS Code
Common Issues:
- Extension not installed → Install MCP extension first
- Workspace vs user settings → Use workspace settings
- Copilot interference → Configure both to work together
- Reload window needed → Use Cmd/Ctrl+Shift+P → Reload Window
Windsurf
Common Issues:
- HTTP transport not configured → Set transport: 'http'
- CORS errors → Allow localhost in settings
- Gemini API key missing → Set GOOGLE_API_KEY
- Port already in use → Change MCP server port
Prevention Tips
Best Practices to Avoid MCP Errors
- Use npx or uvx commands to auto-handle dependencies
- Set environment variables in .env file, not config
- Always restart IDE after config changes
- Check server logs first before changing config
- Use verbose logging to debug: NODE_DEBUG=* node server.js
- Test MCP server standalone before IDE integration
- Keep IDE and MCP SDKs updated to latest versions
- Use absolute paths in configs, avoid relative paths
Frequently Asked Questions
Why does my MCP connection fail immediately?
Immediate connection failures are usually caused by incorrect config file location, invalid JSON syntax, or the MCP server not being installed. Verify your config file is in the correct location for your IDE, validate the JSON syntax, and ensure the MCP server package is installed (use npx/uvx for auto-installation).
How do I check MCP server logs?
In Claude Desktop: Help → View Logs. In Cursor/VS Code: View → Output → Select "MCP" from dropdown. In Windsurf: Output panel → MCP Server logs. Logs show startup errors, connection attempts, and crash information critical for debugging.
What if restarting doesn't fix the connection?
If restarting doesn't help: 1) Test the MCP server standalone in terminal (node server.js), 2) Check environment variables are set correctly, 3) Verify Node.js/Python version meets requirements (Node 18+, Python 3.10+), 4) Clear npm cache or reinstall dependencies, 5) Check for port conflicts with other services.
Can I run multiple MCP servers simultaneously?
Yes! You can run multiple MCP servers at once. Each server must use a different port if using HTTP transport. In your config, list multiple servers in the "mcpServers" object. IDEs will connect to all configured servers simultaneously. Common to run 5-10 MCPs together (GitHub, Postgres, Filesystem, Search, etc).
How do I test if an MCP server works before adding to my IDE?
Test MCP servers standalone: 1) Install the server: npx @modelcontextprotocol/server-github, 2) Run it directly: node node_modules/.bin/mcp-server-github, 3) Check for errors in console. If it starts without errors, it's ready for IDE integration. Use the MCP Inspector tool for interactive testing: npx @modelcontextprotocol/inspector.
Still Having Issues?
Check our IDE-specific setup guides for detailed configuration instructions, or browse verified MCP servers that are tested and working.