Debugging Failing MCP Servers in Claude Code

Debugging Failing MCP Servers in Claude Code

Research date: 2026-02-26

Executive Summary

Claude Code stores per-session JSONL log files for each MCP server in ~/.cache/claude-cli-nodejs/<project-dir>/mcp-logs-<server-name>/. The primary diagnostic tools are: reading these JSONL logs, running claude mcp list and /mcp inside Claude Code, running /doctor, and launching with claude --debug. The most common startup failures are connection timeouts (default 30s), stderr output misinterpreted as errors, Python/Node dependency crashes, and invalid JSON configuration.

Source Inventory

1. MCP Server Log File Locations (Linux)

Primary log directory

~/.cache/claude-cli-nodejs/<project-dir-encoded>/mcp-logs-<server-name>/

Path encoding: The project directory path is encoded by replacing / with - and stripping the leading dash. For example, launching Claude Code from /home/ubuntulinuxqa2/repos/claude_skills creates the cache directory:

~/.cache/claude-cli-nodejs/-home-ubuntulinuxqa2-repos-claude-skills/

Within that directory, each MCP server gets its own subdirectory named mcp-logs-<server-name>:

mcp-logs-exa/
mcp-logs-context7/
mcp-logs-git-xray/
mcp-logs-claude-ai-Ref/
mcp-logs-plugin-episodic-memory-episodic-memory/
mcp-logs-mcp-server-docker/

SOURCE: Confirmed by Anthropic engineer @ashwin-ant in GitHub issue #72 [4]: "MCP errors should appear within ~/Library/Caches/claude-cli-nodejs/ (if you're on a Mac) or ~/.cache/claude-cli (if you're on Linux)." Validated on this system by direct observation [9] -- the actual path on this Linux system is ~/.cache/claude-cli-nodejs/ (with the -nodejs suffix).

Platform-specific log paths

Log file format

Each session creates a JSONL file named with the UTC timestamp of session start:

2026-02-26T15-07-20-951Z.jsonl

Each line is a JSON object with these fields:

{
  "debug": "message text (or absent if error)",
  "error": "error message text (or absent if debug)",
  "timestamp": "2026-02-26T15:07:24.312Z",
  "sessionId": "ecf72873-baea-46b8-950c-19a6af6acf98",
  "cwd": "/home/ubuntulinuxqa2/repos/claude_skills"
}

MCP configuration file locations

SOURCE: Official troubleshooting docs [1], official MCP docs [2].

2. How to Read MCP Server Startup Errors from Logs

Successful startup sequence (4 log lines)

{"debug":"Starting connection with timeout of 30000ms","timestamp":"...","sessionId":"...","cwd":"..."}
{"error":"Server stderr: [informational output from server process]\n","timestamp":"...","sessionId":"...","cwd":"..."}
{"debug":"Successfully connected to stdio server in 2272ms","timestamp":"...","sessionId":"...","cwd":"..."}
{"debug":"Connection established with capabilities: {\"hasTools\":true,...}","timestamp":"...","sessionId":"...","cwd":"..."}

Key observation: The "error" field labeled "Server stderr" does NOT necessarily mean failure. Claude Code logs ALL stderr output from the MCP server process under the "error" key, even informational messages. This is a known bug documented in GitHub issue #17653 [5].

Failed startup sequence (connection closed)

{"debug":"Starting connection with timeout of 30000ms","timestamp":"...","sessionId":"...","cwd":"..."}
{"error":"Server stderr: Traceback (most recent call last):\n  File ... \nNameError: name 'Annotated' is not defined\n","timestamp":"...","sessionId":"...","cwd":"..."}
{"debug":"Connection failed after 2584ms: MCP error -32000: Connection closed","timestamp":"...","sessionId":"...","cwd":"..."}
{"error":"Connection failed: MCP error -32000: Connection closed","timestamp":"...","sessionId":"...","cwd":"..."}

Failed startup sequence (timeout)

{"debug":"Starting connection with timeout of 30000ms","timestamp":"...","sessionId":"...","cwd":"..."}
{"error":"Connection failed: Connection to MCP server \"<name>\" timed out after 5000ms","timestamp":"...","sessionId":"...","cwd":"..."}

SOURCE: Direct observation of log files on this system [9], GitHub issue #72 [4].

How to read the logs

# Find the most recent log file for a specific server
ls -lt ~/.cache/claude-cli-nodejs/<project-dir>/mcp-logs-<server-name>/ | head -5

# Read the most recent log (JSONL format, one JSON object per line)
cat ~/.cache/claude-cli-nodejs/<project-dir>/mcp-logs-<server-name>/<latest-file>.jsonl

# Pretty-print for readability
cat <log-file>.jsonl | python3 -c "import sys,json; [print(json.dumps(json.loads(l),indent=2)) for l in sys.stdin]"

# Filter for errors only
cat <log-file>.jsonl | python3 -c "
import sys, json
for line in sys.stdin:
    obj = json.loads(line)
    if 'error' in obj:
        print(json.dumps(obj, indent=2))
"

# Search all log files for connection failures
grep -r 'Connection failed' ~/.cache/claude-cli-nodejs/<project-dir>/mcp-logs-*/

3. Commands and Files That Show MCP Server Status/Errors

In-session commands (interactive REPL)

SOURCE: Official troubleshooting docs [1]: "/doctor... checks: MCP server configuration errors."

CLI commands (outside Claude Code)

# List all configured MCP servers
claude mcp list

# Get details for a specific server
claude mcp get <server-name>

SOURCE: Official MCP docs [2].

Startup flags for debugging

# Full debug mode (replaces deprecated --mcp-debug)
claude --debug

# Debug with category filtering
claude --debug "mcp"

# Write debug logs to a file
claude --debug-file /tmp/claude-debug.log

# Deprecated but still functional
claude --mcp-debug

SOURCE: claude --help output observed on this system; GitHub issue #72 [4] confirming --mcp-debug was added in March 2025 and later deprecated in favor of --debug.

Environment variables for MCP debugging

# Increase startup timeout to 60 seconds
MCP_TIMEOUT=60000 claude

# Increase output token limit
MAX_MCP_OUTPUT_TOKENS=50000 claude

SOURCE: Official settings docs [3].

4. Common Causes of MCP Server Startup Failures

4.1 Connection timeout (most common)

The MCP server process takes longer than MCP_TIMEOUT (default 30s) to complete initialization and respond to the MCP initialize handshake.

Symptoms in logs:

Connection failed: Connection to MCP server "<name>" timed out after 30000ms

Common causes:

• npx downloading packages on first run (observed in issue #72 [4])
• Python uv run installing dependencies at startup (observed on this system [9])
• Slow network connectivity for remote package registries
• Heavy server initialization logic

Fix: Increase timeout:

MCP_TIMEOUT=60000 claude

4.2 Server process crash (stderr traceback)

The MCP server process exits before completing the MCP handshake.

Symptoms in logs:

Common causes:

• Python import errors / missing dependencies
• Node.js module resolution failures
• Incompatible dependency versions (e.g., Pydantic version mismatch)
• Type annotation errors (e.g., NameError: name 'Annotated' is not defined)

Fix: Run the server command manually outside Claude Code to see the full error:

# For a stdio server, run its command directly:
npx -y @some/mcp-server
# or
uv run python server.py

SOURCE: Observed in kaizen-analysis server logs on this system [9]; issue #72 [4].

4.3 Stderr output misinterpreted as errors (false positive)

Claude Code reports "X MCP servers failed" even though the servers are running correctly, because ANY output to stderr is flagged as an error in the UI.

Symptoms: UI shows failure count, but /mcp shows servers are connected. Log files show "error": "Server stderr: ..." entries containing informational messages like version banners, deprecation warnings, or progress indicators.

SOURCE: GitHub issue #17653 [5] (open bug as of 2026-02-12).

4.4 Invalid JSON configuration

Malformed JSON in .mcp.json, ~/.claude.json, or other config files prevents servers from loading.

Symptoms: /doctor reports configuration errors. Servers do not appear in /mcp listing.

Fix:

# Validate project MCP config
python3 -m json.tool .mcp.json

# Validate global config
python3 -m json.tool ~/.claude.json

SOURCE: Official troubleshooting docs [1]; SFEIR guide [8].

4.5 Incorrect binary path or missing executable

The command field in MCP server configuration points to a binary that does not exist or is not executable.

Symptoms in logs:

Connection failed: spawn <command> ENOENT

Fix:

# Verify the command exists
which npx
which node
which uv

# Check execute permissions
ls -la /path/to/server
chmod +x /path/to/server

SOURCE: SFEIR guide [8]; official MCP docs [2].

4.6 Environment variable misconfiguration

MCP servers requiring API keys or tokens fail when environment variables are not set or not passed through.

Symptoms: Server starts but returns authentication errors, or fails to connect to external services.

Fix: Use --env flag when adding servers:

claude mcp add --transport stdio --env API_KEY=xxx my-server -- npx my-server

Or set in config JSON:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "my-server"],
      "env": {
        "API_KEY": "xxx"
      }
    }
  }
}

SOURCE: Official MCP docs [2].

4.7 Port conflicts (SSE/HTTP transport)

For servers using SSE or HTTP transport, the configured port may already be in use.

Fix:

# Check what is using the port
lsof -i :<port>
# or
ss -tlnp | grep <port>

SOURCE: SFEIR guide [8].

5. Diagnostic Procedure: Identifying Which MCP Servers Are Failing and Why

Step-by-step procedure

Step 1: Run /doctor inside Claude Code
    - Reports MCP server configuration errors
    - Reports malformed JSON, incorrect types
    - Reports plugin and agent loading errors
    SOURCE: [1]

Step 2: Run /mcp inside Claude Code
    - Shows each server with connection status
    - Shows available tools per server
    - Plugin servers appear with plugin indicators
    SOURCE: [2]

Step 3: Check the JSONL log files
    - Navigate to ~/.cache/claude-cli-nodejs/<project-dir>/
    - List mcp-logs-* directories
    - Read the most recent .jsonl file in each failing server's directory
    - Look for:
      * "Connection failed" entries (definitive failure)
      * "Server stderr" entries containing tracebacks or error messages
      * "timed out" messages
    SOURCE: [4], [9]

Step 4: Run the server command manually
    - Extract the command from the config (claude mcp get <name>)
    - Run it in a terminal to see raw stdout/stderr
    SOURCE: [6], [8]

Step 5: Enable debug mode for detailed logs
    - claude --debug
    - Or: claude --debug-file /tmp/mcp-debug.log
    SOURCE: [4], CLI help output

Quick diagnostic commands

# List all configured servers
claude mcp list

# Get config details for a specific server
claude mcp get <server-name>

# Find all recent error logs across all servers for current project
grep -r "Connection failed" ~/.cache/claude-cli-nodejs/-$(pwd | tr '/' '-')/mcp-logs-*/ 2>/dev/null

# Find servers that timed out
grep -r "timed out" ~/.cache/claude-cli-nodejs/-$(pwd | tr '/' '-')/mcp-logs-*/ 2>/dev/null

# List log directories to see which servers have logs
ls -d ~/.cache/claude-cli-nodejs/-$(pwd | tr '/' '-')/mcp-logs-*/

# Read the most recent log for a specific server
ls -t ~/.cache/claude-cli-nodejs/-$(pwd | tr '/' '-')/mcp-logs-<server>/*.jsonl | head -1 | xargs cat

Lifecycle events visible in logs

The JSONL logs capture the full MCP server lifecycle:

1. Startup: "Starting connection with timeout of 30000ms"
2. Stderr capture: "Server stderr: ..." (all stderr output, not only errors)
3. Connection success: "Successfully connected to stdio server in Xms"
4. Capabilities: "Connection established with capabilities: {...}"
5. Shutdown: "Sending SIGINT to MCP server process" then "SIGINT failed, sending SIGTERM" then "MCP server process exited cleanly"
6. Failure: "Connection failed after Xms: MCP error -32000: Connection closed" or "Connection to MCP server ... timed out after Xms"

Known bug: false failure reporting

GitHub issue #17653 [5] documents that Claude Code interprets ANY stderr output as an error. Servers that write informational messages to stderr (version banners, deprecation warnings, progress bars) trigger the "X MCP servers failed" UI message even when the servers are fully functional. The workaround is to check /mcp in-session or read the JSONL logs to verify whether the server actually connected successfully (look for the "Successfully connected" debug line).

Appendix: Observed Log Directory Structure on This System

~/.cache/claude-cli-nodejs/
  -home-ubuntulinuxqa2-repos-claude-skills/
    mcp-logs-claude-ai-Atlassian/
    mcp-logs-claude-ai-Canva/
    mcp-logs-claude-ai-Github-mcp/
    mcp-logs-claude-ai-Gmail/
    mcp-logs-claude-ai-Hex/
    mcp-logs-claude-ai-Hugging-Face/
    mcp-logs-claude-ai-Jam/
    mcp-logs-claude-ai-Mermaid-Chart/
    mcp-logs-claude-ai-Notion/
    mcp-logs-claude-ai-Ref/
    mcp-logs-claude-in-chrome/
    mcp-logs-context7/
    mcp-logs-exa/
    mcp-logs-git-forensics/
    mcp-logs-GitLab-Public-API/
    mcp-logs-git-xray/
    mcp-logs-ide/
    mcp-logs-kernel/
    mcp-logs-mcp-json-yaml-toml/
    mcp-logs-mcp-server-docker/
    mcp-logs-plugin-agentskill-kaizen-kaizen-analysis/
    mcp-logs-plugin-agentskill-kaizen-kaizen-duckdb/
    mcp-logs-plugin-context7-context7/
    mcp-logs-plugin-episodic-memory-episodic-memory/
    mcp-logs-plugin-Notion-notion/
    mcp-logs-plugin-serena-serena/

Each directory contains timestamped .jsonl files (one per session), e.g.:

2026-02-26T15-07-20-951Z.jsonl
2026-02-26T14-54-43-316Z.jsonl