Fix MCP Connection Refused & Claude Desktop Errors [2026]
Resolve "Connection Refused", timeouts, and Cursor errors quickly. Our definitive 2026 troubleshooting guide fixes the most common Model Context Protocol issues.
Quick Answer
90% of MCP Connection Refused or startup errors in Claude Desktop and Cursor are caused by invalid JSON paths, missing environment variables, or using relative paths instead of absolute paths for the Node/Python executables in the `claude_desktop_config.json`.
Error 1: "Connection Refused" or "Failed to Start"
This is the most common error when setting up an MCP server. It means the host application (like Claude Desktop) tried to launch your script but the process crashed immediately.
Solution A: Use Absolute Execution Paths
Claude Desktop runs in its own isolated environment. It does not load your bash profile or ZSH aliases. Therefore, calling `node` or `python` might fail if it's not in the strict system path.
"sqlite": {
"command": "node", // BAD
"args": ["/path/to/server.js"],
"env": {}
}"sqlite": {
"command": "/usr/local/bin/node", // GOOD
"args": ["/absolute/path/to/server.js"],
"env": {}
}Tip: Run which node or where node in your terminal to find the absolute path.
Solution B: Check npx Permissions (MacOS/Linux)
If you are using `npx` (e.g., npx -y @modelcontextprotocol/server-postgres), the first run might prompt the user to type "y" to install the package. Because Claude runs this in the background, the prompt blocks execution forever.
Fix: Ensure you include the `-y` flag in the arguments array to auto-accept installation prompts.
Error 2: Endless Loading or Timeout
If the AI client hangs when trying to use a tool, it usually indicates a breakdown in the `stdio` communication pipe.
- You used print() or console.log(): If your custom MCP script logs debugging text to stdout, it corrupts the JSON-RPC messages intended for Claude. Always use `console.error` for logging inside an MCP server.
- Database locks: If using the SQLite MCP server, ensure another software layer isn't applying an exclusive write lock to the `.sqlite` file at the same time.
- Auth flow hanging: Some cloud-based MCPs (like Google Drive) require an initial OAuth sign-in. If the browser popup doesn't appear, the server hangs waiting for a token. Check the server documentation for CLI auth commands.
Frequently Asked Questions
How do I force restart my MCP servers?
In Cursor, go to Settings > Features > MCP and toggle the server off and on. In Claude Desktop, you must fully quit the application (Cmd/Ctrl + Q) and reopen it to force it to re-read the `claude_desktop_config.json` file.
Where is the specific Claude config file located?
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Still Struggling with Setup?
Try downloading our Package Builder to automatically construct error-free configuration files and bash installation scripts.