BUG: MCP servers silently fail to load in Claude Code sessions
BUG: MCP servers silently fail to load in Claude Code sessions
Problem
Claude Code silently drops MCP servers that fail to initialize during session startup. No error is surfaced to the user or agent. In a 2026-03-13 session on
pal-e-platform, both pal-e-docs and forgejo MCP servers were absent from the tool registry, while notion and woodpecker loaded fine. All four servers are defined in ~/.mcp.json, all import and start correctly when tested manually. Session restart fixed it.Root Cause
Unknown — likely a transient timeout or dependency resolution delay during Claude Code's MCP initialization. No MCP startup logs exist (
~/.claude/logs/ doesn't exist). Claude Code provides zero observability into MCP server health. The private Forgejo PyPI index used by pal-e-docs-sdk and ldraney-forgejo-sdk may contribute to slower uv run startup times, but both servers start fine when tested manually.Recovery
See
sop-mcp-server-recovery for the full recovery procedure. This bug's content has been absorbed into that SOP as part of Phase 5 (plan-pal-e-agency). The SOP covers detection, diagnosis, and recovery for all MCP server failure modes including this silent load issue.Fix (TODO)
Create a
SessionStart hook in claude-custom that verifies expected MCP servers loaded. See Forgejo issue forgejo_admin/claude-custom#76.Related
sop-mcp-server-recovery— the recovery SOP that absorbs this bug's failure modeplan-pal-e-agency— Phase 5 created the recovery SOPsop-claude-config-development— workflow for claude-custom changes