Bug Description

When an MCP server (Streamable HTTP transport) restarts or invalidates sessions, Claude Code's MCP client continues sending the stale Mcp-Session-Id header on every request. The server responds with {"error": "Not Found: invalid session ID"}, and every subsequent MCP tool call fails. The client never attempts to re-initialize.

The only workaround is to fully exit and restart Claude Code (/exit → relaunch), which forces a fresh initialize handshake.

Expected Behavior

Per the MCP Streamable HTTP spec, when the server returns an error indicating the session is no longer valid, the client should discard the stale session ID and perform a new initialize handshake transparently.

Actual Behavior

Claude Code caches the Mcp-Session-Id at connection time and never refreshes it. When the session becomes invalid (server restart, container redeployment, session timeout), all MCP tools break with no recovery path except a full CLI restart.

Frequency & Impact

Over a 7-day period (Feb 14–20, 2026), this bug forced 14 full Claude Code restarts across 14 separate sessions, totaling 53 mentions in session transcripts of stale-session/reconnect issues. On the most active day (Feb 19), 6 out of 6 sessions required at least one restart due to this bug.

Every deployment cycle triggers it: the workflow is build Docker image → deploy to server → container restarts → MCP session invalidated → Claude Code broken → must /exit and relaunch. This is a core development loop that happens multiple times per day.

The restart penalty is high: full context reload, re-reading of project files, loss of conversation flow, and re-establishment of all MCP connections.

Reproduction Steps

1. Configure a Streamable HTTP MCP server in ~/.claude.json:

   {
     "mcpServers": {
       "my-server": {
         "type": "http",
         "url": "https://example.com/mcp",
         "headers": { "Authorization": "Bearer <key>" }
       }
     }
   }

2. Launch Claude Code — MCP tools work (client performs initialize, gets session ID)
3. Restart the MCP server (e.g., docker restart my-container)
4. Try any MCP tool — fails with "invalid session ID" or similar
5. All subsequent MCP tool calls fail
6. Only fix: exit Claude Code entirely and relaunch

Environment

• Claude Code on WSL2 (Linux 6.6.87.2-microsoft-standard-WSL2)
• MCP server: custom Streamable HTTP server in Docker (C++, session-based)
• Transport: Streamable HTTP ("type": "http")

Related Issues

• Feature Request: Add Ability to Reconnect MCP Servers #1026 (closed as feature request — but this is a bug, not a feature request)
• [BUG] ENABLE_EXPERIMENTAL_MCP_CLI=true mode results in intermittent use of stale session ID #14009 (stale session ID with experimental MCP CLI)
• [BUG] MCP HTTP transport fails after ~89 minutes without automatic reconnection #21721 (HTTP transport fails after ~89 min without auto-reconnection)
• MCP /mcp reconnect fails with code-mode server #20684 (reconnect fails with code-mode server)

Suggested Fix

When Mcp-Session-Id returns an HTTP error (404, 410, or a JSON-RPC error indicating invalid session), the client should:

1. Discard the cached session ID
2. Send a new initialize request
3. Cache the new session ID
4. Retry the original request

This is standard session recovery and would eliminate the most disruptive friction point in the MCP workflow.