MCP servers silently fail to load in Claude Code sessions #155

New issue

Open

opened 2026-03-24 20:07:47 +00:00 by forgejo_admin · 2 comments

forgejo_admin commented

2026-03-24 20:07:47 +00:00

Contributor

Type

Bug

Lineage

Standalone -- discovered during operations 2026-03-13

Repo

forgejo_admin/claude-custom

What Broke

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.

Repro Steps

Start a Claude Code session with multiple MCP servers configured in ~/.mcp.json
Observe that some MCP servers may silently fail to load
Tools from failed servers are absent from the tool registry
No error message is displayed

Not reliably reproducible -- appears to be a transient timeout during MCP initialization.

Expected Behavior

All configured MCP servers should load, or a clear error/warning should be shown if one fails to initialize. A SessionStart hook should verify expected servers loaded and warn if any are missing.

Environment

Cluster/namespace: local development (Claude Code on archbox)
Related: sop-mcp-server-recovery covers the recovery procedure
Related issue: forgejo_admin/claude-custom#76

Acceptance Criteria

SessionStart hook checks that expected MCP servers are present in tool registry
Warning or auto-recovery when a server fails to load
Hook documented in agent-workflow SOP

pal-e-agency -- parent project
sop-mcp-server-recovery -- recovery SOP
forgejo_admin/claude-custom#76 -- related issue

### Type Bug ### Lineage Standalone -- discovered during operations 2026-03-13 ### Repo `forgejo_admin/claude-custom` ### What Broke 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. ### Repro Steps 1. Start a Claude Code session with multiple MCP servers configured in `~/.mcp.json` 2. Observe that some MCP servers may silently fail to load 3. Tools from failed servers are absent from the tool registry 4. No error message is displayed Not reliably reproducible -- appears to be a transient timeout during MCP initialization. ### Expected Behavior All configured MCP servers should load, or a clear error/warning should be shown if one fails to initialize. A SessionStart hook should verify expected servers loaded and warn if any are missing. ### Environment - Cluster/namespace: local development (Claude Code on archbox) - Related: `sop-mcp-server-recovery` covers the recovery procedure - Related issue: `forgejo_admin/claude-custom#76` ### Acceptance Criteria - [ ] SessionStart hook checks that expected MCP servers are present in tool registry - [ ] Warning or auto-recovery when a server fails to load - [ ] Hook documented in agent-workflow SOP ### Related - `pal-e-agency` -- parent project - `sop-mcp-server-recovery` -- recovery SOP - `forgejo_admin/claude-custom#76` -- related issue

forgejo_admin commented

2026-03-27 21:32:05 +00:00

Author

Contributor

Scope Review: NEEDS_REFINEMENT

Review note: review-342-2026-03-27

This ticket is a duplicate of the already-closed #76. The check-mcp-servers.sh SessionStart hook already exists (185 lines), is wired in settings.json, and warns when MCP servers fail to load.

Issues found:

All 3 acceptance criteria are already met (or infeasible — auto-recovery requires upstream Claude Code changes)
sop-mcp-server-recovery has stale text saying the hook is "planned but not yet implemented" — needs a 1-line doc update
Related issue #76 is closed with the implementation merged (PR #88)

Recommendation: Close as duplicate of #76, or repurpose narrowly to just the stale SOP doc update (single file, <5 min).

## Scope Review: NEEDS_REFINEMENT Review note: `review-342-2026-03-27` This ticket is a **duplicate** of the already-closed #76. The `check-mcp-servers.sh` SessionStart hook already exists (185 lines), is wired in `settings.json`, and warns when MCP servers fail to load. **Issues found:** - All 3 acceptance criteria are already met (or infeasible — auto-recovery requires upstream Claude Code changes) - `sop-mcp-server-recovery` has stale text saying the hook is "planned but not yet implemented" — needs a 1-line doc update - Related issue #76 is closed with the implementation merged (PR #88) **Recommendation:** Close as duplicate of #76, or repurpose narrowly to just the stale SOP doc update (single file, <5 min).

forgejo_admin commented

2026-03-27 21:44:34 +00:00

Author

Contributor

Closing — Duplicate

Scope review (review-342-2026-03-27) found this work was already done:

hooks/check-mcp-servers.sh exists (185 lines, merged via PR #88)
settings.json line 40 has it wired into SessionStart
sop-mcp-server-recovery documents the recovery procedure

Duplicate of closed #76. The only remaining gap is a stale line in the SOP — tracked separately.

## Closing — Duplicate Scope review (`review-342-2026-03-27`) found this work was already done: - `hooks/check-mcp-servers.sh` exists (185 lines, merged via PR #88) - `settings.json` line 40 has it wired into SessionStart - `sop-mcp-server-recovery` documents the recovery procedure Duplicate of closed #76. The only remaining gap is a stale line in the SOP — tracked separately.