az9713 MCP Doctor
Overview
Diagnoses and repairs broken MCP server configurations. Validates that each server's binary exists and is reachable, then disables broken entries to restore startup.
When to Use
- omp/Claude Code crashes on startup with EPIPE or connection errors
- MCP tools are unavailable or timing out
- After adding/modifying servers in any MCP config
- Periodic health check of all configured servers
Not for: MCP protocol-level debugging, server-side logic issues, or auth token problems (those require testing the server itself).
Workflow
digraph mcp_doctor {
rankdir=LR;
diagnose [label="1. Diagnose\n(run script)" shape=box];
review [label="2. Review\n(show results)" shape=box];
confirm [label="User confirms\ndisabling?" shape=diamond];
fix [label="3. Fix config\n(add disabled:true)" shape=box];
log [label="4. Write log" shape=box];
restart [label="5. Suggest\nrestart" shape=box];
done [label="Done" shape=doublecircle];
diagnose -> review -> confirm;
confirm -> fix [label="yes"];
confirm -> log [label="no"];
fix -> log -> restart -> done;
}
Step 1: Run Diagnostic
bash ~/.claude/skills/mcp-doctor/scripts/mcp_doctor.sh
Output: JSON with sources (configs found) and servers array of { name, status, reason, command, source, configPath }.
The script scans all known MCP config locations:
- User-level:
~/.omp/agent/mcp.json,~/.claude/mcp.json,~/.cursor/mcp.json,~/.codeium/windsurf/mcp_config.json - Project-level:
.omp/mcp.json,.claude/mcp.json,.cursor/mcp.json,.vscode/mcp.json
Step 2: Present Results
Format as a table for the user:
| Server | Status | Command | Issue |
|---|---|---|---|
| example | OK/WARN/FAIL/SKIP | node | (reason if any) |
Step 3: Fix Broken Servers
Ask user: "Should I disable the FAIL servers?"
On confirmation, for each FAIL server, read its configPath and add "disabled": true to the server entry in the correct config file. Preserve existing fields and formatting.
Step 4: Create Log
Write to ~/.claude/logs/mcp-doctor-<YYYY-MM-DD-HHmmss>.log:
MCP Doctor Report - <timestamp>
================================
<server>: <STATUS> - <reason>
...
Actions taken: Disabled <list of servers>
Step 5: Suggest Restart
Tell user to restart omp/Claude Code to apply the fixed config.
Quick Reference
| Status | Meaning | Action |
|---|---|---|
| OK | Binary found, arg paths valid | None |
| WARN | Binary found, arg path missing | Inform user, don't disable |
| FAIL | Binary not found / docker not running | Disable on user confirmation |
| SKIP | Already has "disabled": true |
None |
Common Mistakes
- Disabling WARN servers - Only disable FAIL. WARN means the binary exists; missing arg paths may be created at runtime (e.g., npx downloads packages).
- Skipping the log - Always write the log. It's the audit trail for what changed and why.
- Editing config without reading it fresh - Always re-read
mcp.jsonbefore editing; another process may have changed it. - Forgetting the restart - Config changes only take effect after restart.