MCP Server Troubleshooting: Fix the 10 Most Common Errors

MCP servers are powerful -- until they stop working. And when they break, the error messages range from cryptic to nonexistent.

TL;DR: Most MCP issues are PATH, credentials, or JSON config problems. Run the diagnostic flowchart below. For quick fixes: use absolute paths for npx, verify all env vars are in the config's env block (not just your shell), validate JSON with a linter, and keep total tools under your client's limit (Cursor: 40, Copilot: 128). See also our connection error guide for step-by-step fixes.

Diagnostic Flowchart

Start here when any MCP server is not working:

graph TD
    A[MCP server not working] --> B{node --version<br/>returns 18+?}
    B -->|No| C[Install Node.js 18+]
    B -->|Yes| D{which npx<br/>returns a path?}
    D -->|No| E[Fix PATH or use<br/>absolute npx path]
    D -->|Yes| F{All env vars set<br/>in config env block?}
    F -->|No| G[Add missing env vars<br/>to MCP config]
    F -->|Yes| H{Config is<br/>valid JSON?}
    H -->|No| I[Fix JSON syntax:<br/>trailing commas,<br/>single quotes,<br/>comments]
    H -->|Yes| J{Config file in<br/>correct location?}
    J -->|No| K[Move to correct<br/>path for your client]
    J -->|Yes| L{Total tools under<br/>client limit?}
    L -->|No| M[Remove servers to<br/>get under limit]
    L -->|Yes| N{Server runs<br/>manually in terminal?}
    N -->|No| O[Check server logs<br/>for specific error]
    N -->|Yes| P[PATH issue — use<br/>absolute paths in config]

Before You Start

Run these quick checks first:

node --version          # Node.js installed?
which npx               # npx accessible?
claude mcp list         # Servers configured? (Claude Code)

If any fail, fix those before continuing.

1. ENOENT: Command Not Found

What you see:

Error: spawn npx ENOENT

Why: Your AI client cannot locate the npx binary. Common on macOS where GUI applications do not inherit your shell's PATH, so nvm-managed or Homebrew-installed Node versions are invisible to Claude Desktop, Cursor, and VS Code.

The fix: Use the full absolute path to npx:

which npx
# Example output: /Users/you/.nvm/versions/node/v20.11.0/bin/npx

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

2. Connection Refused / Server Not Starting

What you see: The client reports "connection refused" or says the MCP server failed to start.

Why: The server crashes on startup -- usually a missing environment variable or invalid API key. It exits before the client connects.

The fix: Run the server command manually to see the actual error:

npx supabase-mcp-server

You will likely see something like Error: SUPABASE_ACCESS_TOKEN is not set. Add all required env vars to your config:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "supabase-mcp-server"],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "sbp_your_token_here",
        "SUPABASE_PROJECT_REF": "your_project_ref"
      }
    }
  }
}

For a full list of server-specific env var names, see the server READMEs: Supabase MCP, GitHub MCP, Stripe MCP.

3. Timeout After 60 Seconds

What you see: Long-running MCP tool calls fail silently after exactly 60 seconds.

Why: Claude Code has an internal timeout capped at 60 seconds. Setting MCP_TIMEOUT higher has no effect (GitHub Issue #16837).

The fix: Do not extend the timeout. Restructure your usage:

• Break long operations into smaller tool calls (batch 500 files into groups of 50)
• Use streaming responses where supported
• For database queries, add LIMIT clauses and paginate results

4. 16-Hour Silent Hang

What you see: Claude Code stops responding entirely. Zombie MCP server processes pile up (GitHub Issue #15945).

Why: An MCP server enters a deadlock or infinite wait. Claude Code has no health-check mechanism.

The fix:

ps aux | grep mcp
kill -9 <PID>

Restart Claude Code. Avoid MCP servers that depend on unreliable external services without timeout handling.

5. SSE Disconnection Crashes Session

What you see: Claude Code crashes entirely when an SSE-based MCP server disconnects (GitHub Issue #18557).

Why: SSE transport maintains a persistent HTTP connection. If the server goes down, Claude Code crashes instead of reconnecting.

The fix: Use stdio transport instead of SSE whenever possible. If you must use SSE, run the MCP server in a managed container with automatic restarts. Save work frequently.

6. UI Freeze on Tool Results

What you see: Your editor freezes for 20+ seconds after an MCP tool call completes.

Why: The MCP server returned a large payload and the client's UI thread blocks while rendering it (GitHub Issue #22127).

The fix: Reduce output size. Limit database queries (LIMIT 20), truncate large files, cap response payloads at under 50KB.

7. "Server Started Twice" in Claude Desktop

What you see: Claude Desktop shows a duplicate server error.

Why: Known cosmetic bug. The server is working correctly.

The fix: Ignore it. Restart Claude Desktop if it bothers you.

8. PowerShell Restriction on Windows

What you see:

File cannot be loaded because running scripts is disabled on this system.

The fix:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Or configure your MCP client to use cmd.exe instead of PowerShell. Or use WSL.

9. Wrong Config File Location

What you see: Server added to config, but client does not detect it.

Why: Different clients read MCP config from different locations.

The fix: Correct paths for each client:

For client-specific setup instructions, see our guides for Claude Code, Cursor, Windsurf, and Continue.dev.

10. Tool Count Exceeds Client Limit

What you see: Some MCP servers do not appear in your tool list, or tools that worked before stop being available.

Why: Cursor limits to 40 tools. GitHub Copilot caps at 128. Extras are silently dropped.

The fix: Audit your setup and remove servers you are not actively using. A well-curated stack of 3 to 5 servers is more reliable than 10 servers fighting over tool slots. Read how to build a lean stack for a step-by-step framework.

Client-Specific Issues

Claude Code runs in the terminal and inherits your shell's PATH, so npx-not-found is rare. The main issue is the 60-second timeout for long-running tool calls.

Cursor has a 40-tool limit. Reads config from .cursor/mcp.json (project) or ~/.cursor/mcp.json (global).

VS Code (GitHub Copilot) reads from .vscode/mcp.json in the workspace. Supports an inputs array for prompting users for secrets at runtime.

Windsurf reads from .windsurf/mcp.json. Caches MCP connections aggressively -- fully restart Windsurf after config changes.

How to Test a Server Manually

When all else fails, isolate whether the problem is the server or the client:

# Run the server command directly
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_abc123 npx -y @modelcontextprotocol/server-github

# If it starts and waits for input on stdin, the server works.
# The problem is in your client config (PATH or env vars).

If the server runs in your terminal but not in your client, the problem is almost always PATH resolution or missing env vars. For a deeper dive into connection errors specifically, see our companion guide: How to Fix Common MCP Server Connection Errors.

Avoid configuration headaches entirely by starting with a known-good configuration from stackmcp.dev -- pre-validated with correct package names, env var placeholders, and tool count data.