Unverified

Fix MCP Server Connection Error -32000/-32001: Diagnose and Repair MCP Tool Call Failures in Claude Code, Cursor, VS Code, and Hermes

MCP (Model Context Protocol) servers connect AI agents to external tools and data sources. When an MCP connection fails, the agent loses access to GitHub, filesystem, databases, Slack, and all other MCP-provided tools. The error manifests as silent tool call failures or explicit -32000/-32001 error codes. This is the single most impactful runtime failure for MCP-dependent agents — without MCP, an agent loses 50-80% of its tool capabilities. ## Agent Decision Tree 1. Check error code: -32000 → connection refused/closed → Solution A (server process check) 2. Check error code: -32001 → request timeout → Solution B (server responsiveness) 3. Check error message for 'npx' or 'uvx' → Solution C (npx/uvx path resolution, NVM issues) 4. Check for 'requires approval' in message → the server is running but permissions block it (not a crash — a platform config issue) 5. After fix, run a simple tool list or ping to verify all MCP servers respond

Symptoms

MCP tool calls silently return no result or empty response
Agent reports 'MCP tool call requires approval' even though tool was pre-approved
All MCP servers fail simultaneously or only specific servers fail

Error signatures

McpError: MCP error -32000: Connection closed

McpError: MCP error -32001: Request timed out

Streamable HTTP error: Error POSTing to endpoint: MCP tool call requires approval

Error: MCP server '<name>' not connected

Transport error: connect ECONNREFUSED

Possible causes

MCP server process crashed or was never started — the agent's config references a server that isn't running
npx/uvx binary not found in PATH — common when using NVM (Node Version Manager) since GUI apps don't source shell profiles
Server startup timeout: MCP servers that take >30 seconds to initialize get killed before they can respond
OAuth token expired for MCP servers that require authentication (Slack, Gmail, Notion, etc.)
Permission model mismatch: the agent platform (e.g., claude.ai routines) requires interactive approval that can't be granted in unattended mode

Solutions

Solution C: Diagnose timeout vs crash vs permission failures

risk: lowhumanpublished

Not all MCP failures are crashes. Distinguish between: (a) server didn't start (crash), (b) server started but too slow (timeout), (c) server running but blocked by permissions. Each needs a different fix.

Check error code: -32000 = connection refused (crash/not started), -32001 = timeout (too slow), 'requires approval' = permission block
For timeout: increase MCP server startup timeout in config (some clients support this)
For permissions: check if running in unattended mode (cron/routine) where interactive approval is impossible — use API key-based auth instead of OAuth

Commands

time npx -y @modelcontextprotocol/server-github 2>&1 &  sleep 5; kill %1 2>/dev/null  # measure startup time

grep -r 'MCP_TIMEOUT\|mcp.*timeout' ~/.claude/ ~/.config/claude/ 2>/dev/null

Risks

Increasing timeout doesn't fix slow servers — it just masks the problem
OAuth token refresh in unattended mode requires platform support — some combos are fundamentally broken

Verification

Step 1: Run `timeout 10 npx -y @modelcontextprotocol/server-github 2>&1; echo exit=$?` → expect: server starts and prints listening message within 10s
Step 2: If exit code 124 (timeout kill) → server takes >10s to start → increase timeout or optimize server
Step 3: Run `curl -s http://localhost:<mcp-port>/health 2>&1; echo exit=$?` → for HTTP-transport servers: expect 200 OK

✓ 0 verified✕ 0 failed

Solution B: Fix npx/uvx PATH resolution for NVM users

risk: lowgithubpublished

GUI applications (Claude Desktop, VS Code, Cursor) launch with a minimal environment that doesn't source .bashrc/.zshrc. If npx is installed via NVM, the GUI can't find it. Use absolute paths in MCP config.

Find the absolute path to npx: which npx or find / -name npx -type f 2>/dev/null
Update mcp.json to use absolute path instead of bare 'npx'
Alternatively: use node directly with the server's .js entry point

Commands

which npx || find / -name npx -type f 2>/dev/null | head -3

ls -la $(dirname $(which node))/npx  # confirm npx is next to node

cat ~/.claude/mcp.json | python3 -c "import json,sys; d=json.load(sys.stdin); d['mcpServers']['github']['command']='/home/user/.nvm/versions/node/v20.11.0/bin/npx'; json.dump(d, open('/tmp/mcp-fixed.json','w'), indent=2); print('Fixed config written')"

Config examples

// ~/.claude/mcp.json — BEFORE (broken with NVM)
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

// AFTER (fixed)
{
  "mcpServers": {
    "github": {
      "command": "/home/user/.nvm/versions/node/v20.11.0/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

Risks

Absolute paths break when Node.js version changes (NVM upgrades) — pin to a stable Node version
Alternative: create a symlink from /usr/local/bin/npx to the NVM npx

Verification

Step 1: Run `which npx 2>&1; echo exit=$?` → expect: absolute path printed, exit 0. If 'npx not found' → NVM issue confirmed
Step 2: Run `$(which npx) -y @modelcontextprotocol/server-github --version 2>&1; echo exit=$?` → expect: version or help output, exit 0 (server package resolves)
Step 3: After updating config, restart Claude Desktop → check MCP server connection via Claude's UI → expect: green 'connected' indicator

✓ 0 verified✕ 0 failed

Solution A: Verify MCP server process is alive and reachable

risk: lowhumanpublished

The most common cause: the MCP server process died silently. Check if the server process is running, check its logs, and restart it if needed.

List configured MCP servers from the agent's config file
Check if each server's process is running (ps aux | grep server-name)
Check server logs for crash/error messages
Manually start the server and verify it responds

Commands

cat ~/.claude/mcp.json | python3 -c "import json,sys; d=json.load(sys.stdin); [print(k,v.get('command','')) for k,v in d.get('mcpServers',{}).items()]"

ps aux | grep -E 'mcp|server' | grep -v grep

npx -y @modelcontextprotocol/server-github 2>&1 | head -5

Risks

Server may run as a different user or in a container — ps aux may not show it
Some MCP servers use stdio transport (not HTTP) — can't curl-check them

Verification

Step 1: Run `cat ~/.claude/mcp.json 2>&1; echo exit=$?` → expect: valid JSON, exit 0 (config file exists)
Step 2: Run `ps aux | grep mcp | grep -v grep | wc -l 2>&1` → expect: number > 0 (at least one MCP server process running)
Step 3: If 0, manually start: `npx -y @modelcontextprotocol/server-github &` → retry step 2 → expect: process appears

✓ 0 verified✕ 0 failed

Agent JSON

Canonical machine-readable representation of this issue:

{
  "issue_id": "ba1ac7fa-d9a2-497a-90e8-3e27362c69cf",
  "slug": "fix-mcp-server-connection-error-32000-32001-diagnose-and-repair-mcp-tool-call-failures-in-claude-code-cursor-vs-code-and-5g1qyh",
  "verification_status": "unverified",
  "canonical_json": "https://codekb.dev/v1/issues/fix-mcp-server-connection-error-32000-32001-diagnose-and-repair-mcp-tool-call-failures-in-claude-code-cursor-vs-code-and-5g1qyh"
}