MCP Server Connection Failed — How to Diagnose and Fix It

Each client reads MCP server config from a specific, OS-dependent location. Editing a copy in the wrong folder is the single most common reason a change "does nothing":

If the file doesn't exist yet, create it — the app will not generate it for you automatically in most versions.

A single trailing comma or a smart quote pasted from a doc site breaks the entire config file, and most clients give no error dialog — the server list just silently fails to load. Correct shape:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"]
    }
  }
}

Common mistakes to check for:

• A trailing comma after the last entry in an object or array (invalid in strict JSON).
• Curly "smart" quotes (“ ”) instead of straight " — common when pasting from a website or Word doc.
• Missing the top-level "mcpServers" key — server blocks placed at the root are ignored.
• Backslashes in Windows paths not escaped — use "C:\\\\Users\\\\you\\\\file" or forward slashes instead.

Paste the file into any JSON validator (or run python -m json.tool claude_desktop_config.json) before restarting the app.

This is the most common gotcha and the one people miss the longest. When you type npx in your terminal, your shell (bash/zsh/PowerShell) resolves it using PATH entries set up by nvm, Homebrew, pyenv, etc. Claude Desktop and similar GUI apps are launched by the OS directly — they get a minimal system PATH and often can't find npx or uvx at all, even though they work fine in your terminal.

# macOS / Linux
which npx
# -> /Users/you/.nvm/versions/node/v20.11.0/bin/npx

# Windows (PowerShell or cmd)
where npx
# -> C:\Users\you\AppData\Roaming\npm\npx.cmd

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

If the path and JSON are both correct, the server process may be starting and then crashing immediately — missing an environment variable, a missing dependency, or a bug in the server itself. Don't guess — read the log:

• Claude Desktop (macOS): ~/Library/Logs/Claude/mcp-server-{name}.log
• Claude Desktop (Windows): %APPDATA%\Claude\logs\mcp-server-{name}.log
• Claude Code: server stderr is printed directly in your terminal session — scroll up after the connection failure.
• Cursor: Settings → MCP → click the failed server to expand its error output.

If a required environment variable is missing (common with API-key-based servers), add it to the server's config block:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}

MCP config is read once at process startup. Closing a window or hitting reload does not re-spawn the server processes. You need a true full quit:

• macOS: Cmd+Q, or Claude menu → Quit Claude (closing the window with the red dot leaves it running in the background).
• Windows: right-click the icon in the system tray and choose Quit, or end the process in Task Manager.
• Cursor / Claude Code: for locally-running MCP servers, restart the editor or run the client's MCP reload command if one is exposed in the command palette.

If it still fails after a clean restart with a valid config and absolute paths, it's almost certainly a bug or missing dependency in the server itself — check the server's own GitHub issues for your exact error string.