MCP Server Not Connecting — Troubleshooting Checklist

Your MCP server shows up in the config but Claude Desktop / Cursor / VS Code says it cannot connect. No error details, just silence. This checklist walks through every common cause in order of likelihood. Start at step 1 and work down.

Step 1: Is the JSON Valid?

The most common cause is a JSON syntax error in your config file. A misplaced comma, missing quote, or trailing comma will silently prevent all servers from loading. Paste your config into our Schema Validator or any JSON validator to check.

Common JSON mistakes in MCP configs:

• Trailing comma after the last server entry
• Unescaped backslashes in Windows paths (use \\ or forward slashes /)
• Comments in JSON (JSON does not support comments — remove any // ... lines)

Step 2: Is the Config File in the Right Location?

Each MCP client reads config from a different path:

• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json — but see Step 3 for the MSIX caveat
• Cursor: .cursor/mcp.json in your project root
• VS Code: .vscode/mcp.json in your project root
• Windsurf: ~/.codeium/windsurf/mcp_config.json

Use our Config Generator to create the right format for your client.

Step 3: Windows MSIX Path Issue

Claude Desktop on Windows uses MSIX packaging with filesystem virtualization. When you click "Edit Config" in the app, it may open a file that the app does not actually read. If your config edits have no effect, you are editing the wrong file.

The actual config is under the MSIX virtualized path. Find it by searching for claude_desktop_config.json in %LOCALAPPDATA%\Packages\. Look for a folder starting with AnthropicPBC.Claude_.

Step 4: Can the Command Be Found?

For stdio servers, the client needs to find and execute the command. If you see "spawn X ENOENT" in logs, the command is not in PATH. See our dedicated guide: Fix "spawn npx ENOENT".

Quick check: open a NEW terminal (not one with nvm/mise loaded) and try running the exact command from your config. If it fails there, it will fail in the MCP client too.

Step 5: Is -y Missing from npx?

If your config uses npx without -y, the server will hang waiting for user confirmation that never comes (there is no terminal for the user to type "y"). Always add -y as the first argument:

"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]

Step 6: Is the Config Format Correct for Your Client?

Claude Desktop and Cursor use {"mcpServers": {...}}. VS Code uses {"mcp": {"servers": {...}}}. Using the wrong format means the client silently ignores your servers — no error, just nothing happens.

Step 7: Check Client Logs

If none of the above helps, check the MCP client logs for detailed error messages:

• Claude Desktop (macOS): ~/Library/Logs/Claude/mcp*.log
• Claude Desktop (Windows): %APPDATA%\Claude\logs\mcp*.log
• Cursor: Output panel → select "MCP" from dropdown
• VS Code: Output panel → select "MCP" from dropdown

The log usually contains the actual error (permission denied, port in use, module not found, etc.) that the GUI hides.

Step 8: Remote Server Issues

For servers using SSE or Streamable HTTP transport (not stdio):

• Is the server URL reachable? Try curl https://your-server.com/mcp
• Does the server have CORS headers? Browser-based clients need Access-Control-Allow-Origin
• Is the transport type correct? Use "transport": "sse" for SSE or omit for Streamable HTTP
• Use our Transport Debugger to send test requests and see raw responses

Step 9: Did You Restart?

Most MCP clients do not hot-reload config changes. After editing your config file, fully restart the client application (not just close and reopen the chat — quit the app and relaunch it).