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.
• /.mcp.json — project-scope servers.

Mode detection

Check the arguments:

• No args or status — health check all configured MCP servers.
• trace — 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:

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

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

• stdio — confirm the command exists on $PATH (which ) 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.

1. 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 |

1. 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
- : 

### 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).

1. Find which server provides this tool. The MCP tool naming convention is mcp____; the server slug maps back to a key in ~/.claude.json or .mcp.json.

1. Show the server's configuration:

• Transport (stdio / http / sse).
• Command or URL.
• Args.
• Env vars (always redact secrets — show *** instead of values for any key matching (?i)(token|key|secret|password)).

1. Classify the likely failure mode:

• Auth expired — OAuth token needs refresh.
• Schema mismatch — tool expects different parameters than what was sent.
• Timeout — server takes too long to respond.
• Server down — process crashed or port unreachable.
• Config error — missing env var, wrong path, or stale wrapper script.

Output

## Tool trace: 

Server: 
Transport: stdio | http | sse
Command / URL: 
Status: 

### Configuration
[relevant config — secrets redacted]

### Likely cause

Mode 3: Audit

Steps

1. Run the status check (Mode 1) for the full server list.

1. If tool-usage telemetry exists (some projects log to data/performance/session-log.jsonl or similar), summarise the last 7 days:

• Tools called per server.
• Error rate per server.
• Most-used and least-used servers.

1. Identify:

• Unused servers — configured but never called. Candidates for removal (each one adds startup overhead).
• High-error servers — called often but failing frequently.
• Duplicate capabilities — multiple servers providing similar tools.
• Missing servers — tools referenced in agents/skills but no server configured.

Output

## MCP audit report
Date: YYYY-MM-DD
Servers:  configured

### Health summary
[status table]

### Usage (last 7 days)
| Server | Calls | Errors | Error rate |
|---|---|---|---|
[from session logs, or "no usage data available"]

### Recommendations
1. Remove: 
2. Fix: 
3. Consolidate: 
4. Add: 

Constraints

• Never expose secrets. Redact API keys, tokens, passwords in every output.
• Read-only. This skill does not start, stop, or modify any servers or config.
• Do not delete servers without explicit user approval.
• 401/403/405 on URL servers = reachable, not down. Mark as auth so the operator knows to refresh credentials rather than restart the server.

Quality checklist

• [ ] All MCP config locations checked (~/.claude.json + .mcp.json).
• [ ] Secrets redacted in every output line.
• [ ] False-positive warnings (e.g. spaces in command paths handled by the shell) are flagged as such, not as errors.
• [ ] Recommendations include a one-line rationale, not just an action.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: chacosoldier
• Source: chacosoldier/compabob
• License: MIT

Install and usage instructions live in the source repository linked above.