Fix: MCP Server Not Connecting to Claude Desktop (or Cursor)

Updated 2026-10-15

Almost every “MCP server not connecting” problem is one of six causes. Work through them in order.

Prerequisites

• Claude Desktop or Cursor installed
• The command you use to start your MCP server

Steps

1. Confirm you edited the right config file

In Claude Desktop, Settings → Developer → Edit Config opens the correct file.

2. Validate the JSON

One trailing comma breaks everything silently:

python -m json.tool "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

The top-level key must be mcpServers (camelCase).

3. Fully restart the client

Closing the window isn’t enough. On macOS press Cmd+Q; on Windows quit from the system tray. In Cursor, toggle the server off/on under Settings → MCP (or Tools & Integrations).

4. Read the logs

• Claude Desktop macOS: ~/Library/Logs/Claude/mcp*.log
• Claude Desktop Windows: %APPDATA%\Claude\logs\mcp*.log

tail -n 50 -f ~/Library/Logs/Claude/mcp*.log

The server-specific log (mcp-server-NAME.log) shows its stderr, which usually contains the real error.

5. Fix PATH problems (spawn ... ENOENT)

GUI apps don’t load your shell profile, so npx, uv or python from nvm/pyenv/Homebrew often aren’t found. Use absolute paths:

which npx uv python3

{
  "mcpServers": {
    "filesystem": {
      "command": "/Users/me/.nvm/versions/node/v22.11.0/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Documents"]
    }
  }
}

Likewise, env vars from .zshrc aren’t visible. Put them in the server’s "env": {} block.

6. Run the server by hand

Copy the exact command and args into a terminal. If it crashes, you’ll see why. A healthy stdio server just waits silently for input. Better: test with the Inspector:

npx @modelcontextprotocol/inspector <command> <args...>

7. Check stdout pollution

Stdio servers must write only JSON-RPC to stdout. A stray print() or a startup banner causes errors like Unexpected token ... is not valid JSON in the log. Log to stderr instead.

Common error messages

spawn npx ENOENT / spawn uv ENOENT: step 5.

Server disconnected right after start: the server crashed. Run it by hand (step 6).

Unexpected token / is not valid JSON: stdout pollution (step 7).

Server shows connected but no tools: the server registered no tools, or an older client needs a restart after code changes.

Windows: npx not found even with Node installed: use "command": "cmd", "args": ["/c", "npx", "-y", "..."].

Related

• Build an MCP server in Python
• MCP server for Postgres