mcp-debug

MCP Debugger

A diagnostic tool for MCP (Model Context Protocol) server health and tool execution. Helps identify why MCP tools fail, which servers are down, and which servers are unused or redundant.

Reads MCP config from the two standard locations:

• ~/.claude.json — user-scope servers.
• <project>/.mcp.json — project-scope servers.

Mode detection

Check the arguments:

• No args or status — health check all configured MCP servers.
• trace <tool-name> — trace a specific tool's configuration and likely failure modes.
• audit — full audit with recommendations (unused servers, error patterns, consolidation candidates).

Mode 1: Status (default)

Steps

1. List configured servers via the Claude Code CLI:

   claude mcp list
   

   If the CLI is unavailable, parse ~/.claude.json (top-level mcpServers) and ./.mcp.json directly.

2. For each server, run the lightweight connectivity check appropriate to its transport:

   • stdio — confirm the command exists on $PATH (which <bin>) and the wrapper script is executable.
   • http / sse — curl -s -o /dev/null -w "%{http_code}" the URL.
   • Authenticated remote — a 401 or 403 means reachable, not down. Flag as auth rather than error.

3. Present a status table:

   Server	Transport	Status	Note
   foo	stdio	ok
   bar	http	auth	401 — token may need refresh
   baz	stdio	error	binary not on PATH

4. For warning/error rows, propose the next debugging step (install the binary, refresh the token, check the env var).

Output

## MCP Server Status

[table]

### Issues found
- <server>: <description + suggested fix>

### Summary
[X] ok | [Y] warnings | [Z] errors out of [N] servers

Mode 2: Trace

Steps

1. Parse the tool name from args (e.g. /mcp-debug trace some-tool).

2. Find which server provides this tool. The MCP tool naming convention is mcp__<server-slug>__<tool-name>; the server slug maps back to a key in ~/.claude.json or .mcp.json.