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. A vague "connection refused," a silent hang that eats your afternoon, or a UI freeze that forces you to kill your editor.

This guide covers the 10 most common MCP server errors across Claude Code, Claude Desktop, Cursor, VS Code, and Windsurf. Each includes the symptom, root cause, and a concrete fix.

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

Or a variation like command not found: npx when the MCP server tries to start.

Why it happens:

Your AI client cannot locate the npx binary. This is 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 instead of relying on PATH resolution.

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

Then update your MCP config to use that full path:

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

If you are on nvm, also verify you are running a supported Node version (18+). Some MCP servers silently fail on older versions.

2. Connection Refused / Server Not Starting

What you see:

The client reports "connection refused" or simply says the MCP server failed to start, with no further detail.

Why it happens:

The MCP server process crashes on startup — usually a missing environment variable or invalid API key. It exits before the client can connect, so you only get a generic error.

The fix:

Run the server command manually in your terminal to see the actual error output:

# Example: run the Supabase MCP server directly
npx supabase-mcp-server

You will likely see something like Error: SUPABASE_ACCESS_TOKEN is not set. Check that all required environment variables are defined in your MCP config:

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

Also verify API keys are valid and not expired. A surprising number of "server not starting" reports come down to a rotated token.

3. Timeout After 60 Seconds

What you see:

Long-running MCP tool calls fail silently or return a timeout error after exactly 60 seconds, even though you set MCP_TIMEOUT to a higher value.

Why it happens:

Claude Code has an internal timeout that silently caps at 60 seconds. Setting MCP_TIMEOUT to values longer than 60 seconds has no effect (GitHub Issue #16837). The timeout triggers, the tool call is abandoned, and you get either a vague error or no feedback at all.

The fix:

Do not rely on extending the timeout. Instead, restructure your MCP usage:

• Break long operations into smaller tool calls. Instead of one call that processes 500 files, batch them into groups of 50.
• Use streaming responses where the MCP server supports it, so the client sees ongoing activity and does not trigger a timeout.
• For database queries, add LIMIT clauses and paginate results.

If you are building your own MCP server, ensure no single tool call takes longer than 30 seconds. That gives you a safety margin below the hard cap.

4. 16-Hour Silent Hang

What you see:

Claude Code stops responding entirely. No error, no output, no progress. It just hangs. If you check your system processes, you find zombie MCP server processes piling up (GitHub Issue #15945).

Why it happens:

An MCP server enters a bad state — a deadlock or infinite wait on an external resource — and Claude Code has no health-check mechanism to detect it. The process stays alive while the client waits indefinitely.

The fix:

First, kill the zombie processes:

# Find hanging MCP processes
ps aux | grep mcp

# Kill them
kill -9 <PID>

Then restart Claude Code. To prevent this in the future:

• Add timeout logic inside your custom MCP servers. If a tool call takes longer than 45 seconds, return an error response instead of hanging.
• Monitor for stuck processes periodically if you run long coding sessions.
• Avoid MCP servers that depend on unreliable external services without their own timeout handling.

5. SSE Disconnection Crashes Session

What you see:

Claude Code crashes entirely — the whole session is lost — when an SSE-based (Server-Sent Events) MCP server disconnects unexpectedly (GitHub Issue #18557).

Why it happens:

SSE transport maintains a persistent HTTP connection. If the server goes down (Docker restart, network blip, crash), Claude Code does not handle the disconnection gracefully — it crashes instead of reconnecting.

The fix:

Use stdio transport instead of SSE whenever possible. Stdio is the default for most MCP servers and is more resilient because the client manages the server process lifecycle directly.

If you must use SSE (for remote servers), ensure the infrastructure is stable:

• Run the MCP server in a managed container with automatic restarts.
• Use a reverse proxy with health checks.
• Save your work frequently — if the connection drops, you will lose your session context.

6. UI Freeze on Tool Results

What you see:

Your editor freezes for 20 or more seconds after an MCP tool call completes. The server itself finished in under 100ms, but the UI becomes completely unresponsive (GitHub Issue #22127).

Why it happens:

The MCP server returned a large payload — a full file listing, verbose database dump, or massive JSON blob — and the client's UI thread blocks while rendering it.

The fix:

Reduce the size of your tool call outputs:

• If your MCP server returns file contents, truncate or summarize large files.
• For database queries, limit rows returned: SELECT * FROM users LIMIT 20 instead of returning thousands of rows.
• If you control the MCP server, cap response payloads at a reasonable size (under 50KB is a good target).

This is a client-side rendering issue, not a server issue. The fix is always to send less data.

7. "Server Started Twice" in Claude Desktop

What you see:

Claude Desktop shows an error that your MCP server was "started twice" or shows a duplicate entry in the server list. The server still works normally.

Why it happens:

This is a known cosmetic bug in Claude Desktop. The app occasionally triggers the server initialization sequence twice. The duplicate gets cleaned up, but the error message persists in the UI.

The fix:

Ignore it. The server is working correctly. If it bothers you, restart Claude Desktop — the error sometimes does not reappear on the second launch. This does not affect functionality or stability.

8. PowerShell Restriction on Windows

What you see:

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

This appears when trying to start any MCP server on Windows that uses a .ps1 script or runs through PowerShell.

Why it happens:

Windows ships with a restrictive execution policy that blocks unsigned scripts. Many npm packages used by MCP servers rely on PowerShell scripts internally.

The fix:

Option 1 — Change the execution policy:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Option 2 — Configure your MCP client to use cmd.exe instead of PowerShell. In Cursor, for example, you can specify the shell in your MCP config or set your default terminal to Command Prompt.

Option 3 — Use WSL (Windows Subsystem for Linux) for your development environment, which avoids the issue entirely.

9. Wrong Config File Location

What you see:

You have added an MCP server to your config file, but the client does not detect it. The server list is empty even though the file exists and the JSON is valid.

Why it happens:

Different clients read MCP config from different locations, and even official docs have contained incorrect paths. Confusing global vs. project-level config is one of the most common mistakes.

The fix:

Verify which config file your client is actually reading:

# Claude Code — list configured servers
claude mcp list

# Check for project-level config
ls -la .mcp.json

# Check for global config
ls -la ~/.claude/

Here are the correct paths for each major client:

If you have configs in multiple locations, the project-level config typically takes precedence.

10. Tool Count Exceeds Client Limit

What you see:

Some MCP servers do not appear in your tool list, or the client warns that the maximum number of tools has been exceeded. Tools that worked before suddenly stop being available.

Why it happens:

Each AI client caps the number of MCP tools it can register. Cursor limits you to 40 tools. GitHub Copilot caps at 128. Exceed the limit and extras are silently dropped.

The fix:

Audit your MCP server setup:

# See how many tools each server provides
claude mcp list

Remove servers you are not actively using. If you need multiple servers, choose ones with focused tool sets rather than bloated all-in-one solutions.

A well-curated stack of 3 to 5 MCP servers is more reliable than 10 servers fighting over tool slots. Focus on the servers that match your actual workflow.

Stop Debugging, Start Building

Most MCP issues come from misconfiguration — wrong paths, missing keys, oversized payloads, or too many servers at once. A clean, intentional setup avoids 90% of these problems.

That is exactly what stackmcp.dev provides. Every stack is pre-tested across all major AI clients. Configs are generated with correct paths, environment variable placeholders, and a curated server count that stays within client limits. Pick a stack that matches your workflow and get a working config in under a minute.

Stop fighting your tools. Let them work for you.