Skip to content
MCP & Plugins Intermediate

Debug MCP Connections

Diagnose and fix MCP server connection failures using init events and manual testing

Command

"color:#9CA3AF;font-style:italic"># 1. Check init event "color:#7C5CFC">for server status:
$ "color:#7C5CFC">claude -p "List tools" "color:#d97757">--output-format stream-json "color:#d97757">--verbose \
    "color:#d97757">--mcp-config ./mcp.json | head -1 | "color:#7C5CFC">jq '.mcp_servers'
  
"color:#9CA3AF;font-style:italic"># 2. Test server manually:
$ "color:#7C5CFC">echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}' | \
    "color:#7C5CFC">npx -y @anthropic-ai/mcp-server-filesystem /tmp
  
"color:#9CA3AF;font-style:italic"># 3. Use strict mode "color:#7C5CFC">for fast failure:
$ "color:#7C5CFC">claude -p "test" "color:#d97757">--mcp-config ./mcp.json "color:#d97757">--strict-mcp-config

Response

[
  { "name": "filesystem", "status": "connected" },
  { "name": "database", "status": "error" }
]

Parsing Code

059669">">// Parse init event to verify MCP status:
059669">">const initEvent = JSON.parse(firstLine);
059669">">const broken = initEvent.mcp_servers
  .filter(s => s.status !== 059669059669">">'connected');
059669">">if (broken.length) {
  059669">">console.error(059669">'Failed MCP servers:', broken.map(s => s.name));
}

Gotchas

! Common failure causes: missing binary, missing env vars, port conflicts, disabledMcpServers in ~/.claude.json
! Each MCP server shows status: 'connected' or 'error' in the init event

Related Recipes