← ClaudeAtlas

mcp-server-diagnosticslisted

MCP server hangs, fails, or reads unavailable - handshake checks, provider CLI differences on Windows, path and launcher faults, and per-provider registration repair.
SenjuWoo/Ultimate-AI-Starter-Bundle · ★ 7 · AI & Automation · score 78
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