MCP Setup Troubleshooting

MCP setup problems tend to cluster around three failure modes: command resolution fails silently, configuration syntax errors fail silently, and too many tools degrade AI performance. Knowing where to look and what patterns to apply fixes most issues in under ten minutes.

macOS PATH Problems

The most common failure on macOS. Applications launched from Finder or the Dock don’t inherit your shell’s PATH. When Claude Desktop or another GUI AI client tries to launch an MCP server with a command like npx or uvx, it can’t find the binary.

The symptom: the server doesn’t appear in your AI client, and there’s no obvious error message. The logs (see below) will show something like spawn npx ENOENT — “No such file or directory.”

The fix: use absolute paths in your MCP configuration.

{
  "mcpServers": {
    "my-server": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "@antv/mcp-server-chart"]
    }
  }
}

Find your binary paths:

which npx    # → /opt/homebrew/bin/npx  (Homebrew on Apple Silicon)
which uvx    # → /Users/you/.local/bin/uvx
which node   # → /opt/homebrew/bin/node

The Homebrew prefix varies by chip: /opt/homebrew on Apple Silicon, /usr/local on Intel. Don’t assume — run which to confirm.

Alternatively, configure your MCP server to use env to set PATH explicitly:

{
  "mcpServers": {
    "my-server": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/full/path/to/server.js"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

For Claude Code (used from the terminal, which inherits your shell PATH), this is less often a problem. GUI clients need absolute paths.

Silent JSON Configuration Failures

MCP configuration files are JSON. JSON does not allow trailing commas. It does not allow comments. A single syntax error causes the entire configuration to be silently ignored — the server just doesn’t load, with no error visible to the user.

// This is invalid JSON — comments not allowed
{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@antv/mcp-server-chart"],  // trailing comma — also invalid
    }
  }
}

The fix: validate your configuration file before restarting the client.

# macOS / Linux
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool

# Or use a JSON linter
npx jsonlint ~/Library/Application\ Support/Claude/claude_desktop_config.json

Use a code editor with JSON syntax highlighting and error underlining (VS Code, Zed, etc.) as your default editor for these files. The syntax error will be underlined before you save it.

Common JSON syntax errors:

• Trailing comma after the last item in an object or array
• Comments (// or /* */)
• Single quotes instead of double quotes
• Unescaped special characters in strings

Where to Find Debug Logs

Claude Desktop writes MCP server logs to:

~/Library/Logs/Claude/mcp-server-[server-name].log

Open these with Console.app (search for “mcp”) or from the terminal:

tail -f ~/Library/Logs/Claude/mcp-server-my-server.log

The logs capture both stdout and stderr from your server process. This is where you’ll find:

• Process launch errors (the spawn ENOENT for PATH problems)
• Server startup exceptions
• Tool invocation errors
• Any logging your server does to stderr

For Claude Code, run the MCP server directly in a terminal to see its output:

uv run /path/to/server.py

This is useful when you want to see server-side output without routing through the AI client’s log files.

Tool Count and AI Performance

Research on AI tool use shows a non-linear degradation in success rate as the number of available tools increases. With 50 tools, the AI achieves roughly 31% success on complex tasks. With 8 focused tools, success rates reach 89%.

The mechanism is attention. When the model has 50 tools to reason about, it expends tokens on tool selection that could go toward solving the actual problem. It also makes more mistakes about which tool to call, generating invalid parameters or choosing the wrong tool for the task.

The practical implication for MCP server design: if you can’t explain what each tool does in a sentence, consolidate.

Signs you have too many tools:

• The AI frequently picks the wrong tool for a request
• Tool descriptions are similar to each other (the AI can’t distinguish between them)
• Multiple tools do variations of the same thing (get_revenue, get_total_revenue, get_revenue_by_period)

Consolidation strategies:

• Merge tools that differ only in parameters (add optional parameters instead of separate tools)
• Remove tools that are never used in practice
• Split into separate MCP servers by domain — keep the data quality server separate from the data catalog server, so each server has a focused toolset

For teams connecting multiple data sources (BigQuery + dbt + GA4 + Looker), each source should be its own server rather than one mega-server with tools for everything. The AI client loads the relevant servers per conversation rather than having every tool available simultaneously. See MCP Tool Design Patterns for the design principles that prevent tool proliferation.

Restart Requirements

MCP servers are loaded at client startup. Changes to server code or configuration require restarting the AI client to take effect.

A common debugging trap: you fix the code, run the tool again, get the same error. The old server is still running. Fully quit and reopen the client (Cmd+Q, not just closing the window on macOS).

For active development with Claude Code:

# Verify the server is running with your changes
claude mcp list
# Remove and re-add the server after code changes
claude mcp remove my-server
claude mcp add my-server -- uv run /path/to/server.py

The MCP Inspector as a First Debug Step

Before debugging in the actual AI client, verify the server works in isolation:

npx @modelcontextprotocol/inspector uv run server.py

The Inspector is a browser-based test client. It shows all available tools, lets you invoke them with test inputs, and displays raw responses. If a tool doesn’t work in the Inspector, it won’t work in Claude — but the Inspector gives you cleaner error output.

The MCP Server Testing and Debugging note covers the full testing workflow, including a critical gotcha: logging to stdout from your server will corrupt the JSON-RPC protocol. Use stderr for all server-side logging.