BUG: MCP servers silently fail to load in Claude Code sessions

bug-mcp-silent-load-failure Doc

bug open

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.
  • sop-mcp-server-recovery — the recovery SOP that absorbs this bug's failure mode
  • plan-pal-e-agency — Phase 5 created the recovery SOP
  • sop-claude-config-development — workflow for claude-custom changes