MCP Tool Error

What MCP errors look like

In Claude Code UI:

MCP server "my-server" connection failed
Error: spawn /usr/local/bin/my-mcp-server ENOENT

MCP error -32603: Internal error

Tool "read_file" failed: MCP server disconnected
Could not connect to MCP server "filesystem" after 3 attempts

In the API response (when using tool_use in the Messages API):

{
  "type": "tool_result",
  "tool_use_id": "toolu_01...",
  "is_error": true,
  "content": "MCP tool execution failed: connection timeout"
}

Step 1 — Check MCP logs (fastest diagnosis)

# macOS
tail -100 ~/Library/Logs/Claude/mcp.log
tail -100 ~/Library/Logs/Claude/mcp-server-YOUR-SERVER-NAME.log

# Linux
tail -100 ~/.config/claude/logs/mcp.log

# Windows PowerShell
Get-Content "$env:APPDATA\Claude\logs\mcp.log" -Tail 100

Common log messages and their meanings:

# Server binary not found
Error: spawn /path/to/server ENOENT
→ Fix: install the MCP server or fix the path in config

# Server exited immediately
Server process exited with code 1
→ Fix: run the server command manually to see the startup error

# JSON-RPC protocol error
Error parsing response: SyntaxError: Unexpected token
→ Fix: the server returned non-JSON output (check for print/console.log debug output)

# Timeout
Tool call timed out after 30000ms
→ Fix: increase MCP timeout in settings or optimize the tool's operation

Step 2 — Validate your MCP config

Check your claude_desktop_config.json (Claude Desktop) or project .mcp.json:

# macOS config location
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Linux
cat ~/.config/claude/claude_desktop_config.json

Valid config structure:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {
        "NODE_ENV": "production"
      }
    },
    "my-python-server": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "MY_API_KEY": "..."
      }
    }
  }
}

Common config mistakes:

• Using relative paths — always use absolute paths for command and args
• Missing -y flag with npx (causes interactive prompt that hangs)
• Wrong Node/Python version — the MCP server's runtime may differ from your shell's
• Missing environment variables the server requires

Step 3 — Test the MCP server manually

Run the server command in your terminal to see the raw startup output:

# Test the exact command from your config
npx -y @modelcontextprotocol/server-filesystem /tmp

# You should see something like:
# MCP Filesystem Server running on stdio

# If it fails, you'll see the real error:
# Error: Cannot find module 'xyz'  → npm install needed
# SyntaxError: ...                 → server code bug
# Permission denied                → make the script executable

# For Python MCP servers:
python /absolute/path/to/server.py
# or
uv run /absolute/path/to/server.py

Step 4 — Fix ENOENT errors (binary not found)

# ENOENT means the executable isn't in PATH when Claude Code launches
# Claude Code may use a different PATH than your shell

# Option A: use full absolute path
{
  "command": "/usr/local/bin/node",
  "args": ["/absolute/path/to/mcp-server.js"]
}

# Option B: use a wrapper script that sets up the environment
# /usr/local/bin/run-mcp-server.sh:
#!/bin/bash
export PATH="/usr/local/bin:/opt/homebrew/bin:$PATH"
export NODE_ENV=production
exec npx -y @modelcontextprotocol/server-filesystem "$@"

# Find where node/python actually lives:
which node    # → /usr/local/bin/node  (use this in config)
which python  # → /opt/homebrew/bin/python3

Step 5 — Debug JSON-RPC protocol errors

MCP uses JSON-RPC over stdio. If your server outputs anything that isn't valid JSON-RPC, Claude Code will fail:

# Bad: print/console.log debug output breaks the protocol
# Python server — WRONG:
print("Starting server...")  # This breaks JSON-RPC!

# Python server — RIGHT:
import sys
print("Starting server...", file=sys.stderr)  # stderr only

# Node.js server — WRONG:
console.log("debug");  # breaks JSON-RPC

# Node.js server — RIGHT:
console.error("debug");  # stderr only

MCP error codes reference

Code	Meaning	Fix
-32700	Parse error	Server sent non-JSON; check for debug prints to stdout
-32600	Invalid request	Protocol version mismatch; update MCP server
-32601	Method not found	Tool name mismatch between config and server capabilities
-32602	Invalid params	Tool called with wrong parameter types
-32603	Internal error	Server threw an exception; check server logs

Project-scoped MCP with .mcp.json

For project-specific MCP servers (Claude Code only), create .mcp.json at the project root:

{
  "mcpServers": {
    "project-tools": {
      "command": "node",
      "args": ["./tools/mcp-server.js"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

# The ${VAR} syntax inherits from your environment
# .mcp.json is loaded automatically when Claude Code opens the project