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.