"Could not connect to MCP server" means the MCP client (your IDE or Claude Desktop) attempted to establish a connection and failed before the handshake could begin. Unlike error -32000 where the connection starts then drops, this error means no connection was established at all.

The short answer: The three most common causes are: (1) the server binary or URL is unreachable, (2) the config JSON has a syntax error that silently breaks all servers, or (3) the IDE can't find the runtime (node, python, npx) because it uses a different PATH than your terminal.

---

If the error mentions "mcp-registry" specifically

If you see Could not connect to MCP server mcp-registry in Claude Desktop, this is a known application-level issue — not a problem with your configuration.

Claude Desktop includes an internal mcp-registry service for its built-in features. When this internal service fails to connect, it surfaces the error as a toast notification. This can happen:

• After a Claude Desktop update that changed internal connection handling
• When the app attempts to reuse a stale connection instance
• Intermittently on startup before internal services finish initializing

What to do:

1. Check if your actual servers work. If the MCP servers you configured (filesystem, GitHub, etc.) are functioning correctly, the mcp-registry error is cosmetic and can be safely ignored.
2. Update Claude Desktop to the latest version — this error has been patched in subsequent releases.
3. Full quit and restart — Cmd+Q on macOS, right-click taskbar icon → Exit on Windows. Don't just close the window.

If only mcp-registry errors appear but your custom servers work fine, you don't need to change anything in your config.

---

Diagnosing connection failures for your own servers

Step 1 — Verify config syntax

A single JSON syntax error — a missing comma, unclosed bracket, or trailing comma — breaks the entire config file. All servers stop loading, not just the new one.

bashCOPY
# Validate your config file
# macOS/Linux
cat ~/.cursor/mcp.json | python3 -m json.tool

# Windows (PowerShell)
Get-Content "$env:USERPROFILE\.cursor\mcp.json" | python -m json.tool

Or paste it into jsonlint.com. If the validator shows an error, fix it before debugging anything else.

Step 2 — Check the config key name

Different tools use different root keys, and using the wrong one produces no error — the config is valid JSON, the tool just ignores it:

If you copied a config from a Cursor guide into VS Code (or vice versa), this is likely the problem.

Step 3 — For stdio servers: verify the command exists

The IDE runs the command from your config as a subprocess. If the binary doesn't exist at that path, the connection fails immediately.

bashCOPY
# Check if the command your config references actually exists
which npx          # macOS/Linux
where npx          # Windows

# If you use nvm, the path your IDE sees may differ from your terminal
# Use the absolute path instead
which node
# → /Users/you/.nvm/versions/node/v22.4.0/bin/node

Then use the absolute path in your config:

jsonCOPY
{
  "mcpServers": {
    "my-server": {
      "command": "/Users/you/.nvm/versions/node/v22.4.0/bin/npx",
      "args": ["-y", "some-mcp-package"]
    }
  }
}

Step 4 — For HTTP servers: verify the URL is reachable

bashCOPY
# Test if the server responds at all
curl -s -w "\nHTTP code: %{http_code}\nTime: %{time_total}s\n" \
  -X POST https://your-server-url/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}'

Step 5 — Check environment variables

If the server requires API keys or tokens, they must be in the env block of your config — not in your shell's .bashrc or .zshrc:

jsonCOPY
{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "some-mcp-package"],
      "env": {
        "API_KEY": "your-api-key-here"
      }
    }
  }
}

IDEs don't inherit your shell environment. If the server crashes on startup because a required env var is missing, the IDE reports "could not connect."

---

Reading connection error logs

Cursor

Help → Toggle Developer Tools → Console tab
Output panel (Ctrl+Shift+U) → select "MCP" from dropdown

Look for spawn ENOENT (command not found), ECONNREFUSED (server unreachable), or ETIMEDOUT (network timeout).

VS Code

Output panel (Ctrl+Shift+U) → select "MCP" from dropdown

Claude Desktop

bashCOPY
# macOS
tail -f ~/Library/Logs/Claude/mcp*.log

# Windows
type %APPDATA%\Claude\logs\mcp*.log

Look for spawn errors — they almost always mean the command path is wrong or the binary doesn't exist.

---

Quick diagnostic table

---

Verify recovery

1. Run npx @modelcontextprotocol/inspector node your-server.js to confirm the server works independently of any IDE
2. Use the MCP Playground for remote HTTP servers
3. Restart the IDE fully after fixing the config
4. Confirm the server shows a green dot or active status in IDE settings

For a complete testing workflow, see How to Test MCP Servers.

---

Related troubleshooting

• MCP Error -32000 Connection Closed — connection starts then drops (different from "could not connect")
• MCP Error -32601 Method Not Found — connection works but methods are unknown
• No Working IDE Endpoint Available — config parsed but endpoints failed health checks
• MCP Server Not Working? Complete Guide — all failure modes in one place
• How to Test MCP Servers — debug handshakes, tool calls, and response times

IDE setup guides: VS Code · Cursor · Claude Desktop · Windsurf