mcp-server-diagnosticslisted
Install: claude install-skill SenjuWoo/Ultimate-AI-Starter-Bundle
# MCP Server Diagnostics
## When to Use
- A client (Grok, Claude Code, Codex, Kimi, Hermes) hangs at session start, "does not reply", or reports an MCP server unavailable
- A server that "used to work" now fails to start or connect
- You changed something (tool update, cleanup, uninstall) and MCP broke after
## Diagnosis Ladder (fastest evidence first)
1. **Client-side evidence.** Find the client's per-server logs before theorizing:
- Grok: `~/.grok/logs/mcp/<server>.stderr.log` (one file per server; a healthy npx spawn shows `npm notice run ...`; an empty file with a fresh mtime means the process died before printing)
- Also `~/.grok/logs/unified.jsonl` (`session.create.*` carries `mcp_server_count`)
- Ask the user what the client UI shows (`/mcps` in Grok). Zero output + "unavailable" ≠ slow start — it is usually an instant death.
2. **Reproduce the spawn manually.** Run the exact configured command with a JSON-RPC `initialize` probe and a timeout:
`printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}\n' | timeout 25 <command>`
Must return JSON, not hang. Also probe `tools/list`.
3. **Check the config the client actually uses.** Precedence differs per client — see `references/providers-windows.md`.
4. **Look for the classic killers** (below), then apply the matching fix.
## Classic Killers & Fixes
| Symptom | Cause | Fix |
|---|---|---|
| Client han