MCP Server Not Connecting in Claude Desktop

Why MCP server connections fail

Claude Desktop spawns MCP servers as child processes in a restricted shell environment that does not inherit your terminal's PATH. Tools installed via Homebrew, nvm, pyenv, asdf, or system package managers are invisible to it. The server silently fails to start, no tools icon appears, and there is often no error message in the Claude UI.

The four most common causes in order of frequency:

1. Bare command in config — "command": "npx" or "command": "uvx" when those binaries are not on the restricted PATH
2. JSON syntax error in claude_desktop_config.json — one bad comma silently disables all servers
3. Claude Desktop not fully restarted after editing the config
4. Missing or placeholder env var — the server starts and immediately crashes

Step 1 — read the MCP log

Before changing anything, check what actually happened. Each server writes its own log:

# macOS
ls ~/Library/Logs/Claude/
tail -50 ~/Library/Logs/Claude/mcp-server-YOURSERVERNAME.log

# Windows (PowerShell)
ls "$env:APPDATA\Claude\logs\"
Get-Content "$env:APPDATA\Claude\logs\mcp-server-YOURSERVERNAME.log" -Tail 50

# Linux
ls ~/.config/Claude/logs/
tail -50 ~/.config/Claude/logs/mcp-server-YOURSERVERNAME.log

Look for: spawn ENOENT, MODULE_NOT_FOUND, ModuleNotFoundError, EACCES, or any HTTP 401/403 error. Each has a specific fix — see the spawn ENOENT guide if you see that error.

Step 2 — fix the PATH issue (most common cause)

Replace bare commands with absolute paths in your config:

# macOS/Linux - find absolute paths
which npx     # e.g. /usr/local/bin/npx or /opt/homebrew/bin/npx
which uvx     # e.g. /Users/you/.local/bin/uvx
which node    # if using node directly

# Windows - find absolute paths
where npx     # e.g. C:\Users\you\AppData\Roaming\npm\npx.cmd
where uvx

Then update your config to use the full path:

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

Step 3 — validate your JSON config

A single misplaced comma, missing brace, or unescaped character silently disables every MCP server with no error in the Claude UI.

# macOS/Linux
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool

# Windows (PowerShell)
Get-Content "$env:APPDATA\Claude\claude_desktop_config.json" | ConvertFrom-Json

If either command throws an error, your JSON is invalid. Common mistakes: trailing comma after the last item, unescaped backslash in a Windows path, missing closing brace. Fix the error, save, then continue. You can also paste the config into the free MCP Config Auditor for a visual per-server report.

The correct top-level structure:

{
  "mcpServers": {
    "server-name": {
      "command": "/absolute/path/to/npx",
      "args": ["-y", "package-name"]
    }
  }
}

Step 4 — fully quit and restart Claude Desktop

Editing the config while Claude Desktop is running has no effect until you fully restart it.

• macOS: Press Cmd+Q (or right-click the Dock icon → Quit). Closing the window with Cmd+W leaves the process running.
• Windows: Right-click the Claude Desktop icon in the system tray → Quit. Using the window X button leaves the process running.
• Linux: Kill the process: pkill -f "Claude Desktop" or use your desktop environment's quit option.

After restarting, wait 10–15 seconds before checking for the tools (hammer) icon. Servers that use npx download packages on first run and can take 30–60 seconds.

Step 5 — check environment variables

If the server appears to start but tools never show up, a missing or placeholder API key may be causing it to crash immediately after launch. Inspect your config for placeholder values:

{
  "mcpServers": {
    "brave-search": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "BSAbc123realkey"
      }
    }
  }
}

Replace any placeholder values ("your-token-here", "REPLACE_ME", "") with real credentials. If you do not have the key yet, remove that server entry entirely — an empty required env var causes a silent crash every time.

FAQ