OAuth MCP connectors: random mid-session "disconnected" requiring /mcp Reauthenticate (persistent across versions)

Summary

Remote OAuth-based MCP connectors get silently dropped to a failed / disconnected state mid-session, at random, on every Claude Code session. The only workaround is /mcp → Reauthenticate, which works without a restart but interrupts the flow every time. The problem affects all my OAuth connectors equally and has persisted across many Claude Code releases.

This issue exists despite multiple prior reports being closed, several as "completed" or "duplicate":

The pattern of marking #24317 as completed despite immediate user pushback, plus aggressive auto-deduplication and 7-day auto-lock, dilutes vote counts and makes the real prevalence invisible. Opening this consolidated report to document that the underlying behavior is still occurring on the latest version.

Environment

Symptoms

1. Random mid-session disconnects. Not at session start, not at a fixed time interval — happens at unpredictable moments while the session is active and I'm actively using Claude Code.
2. /mcp shows the connector as failed / disconnected when this happens. The UI knows the token is bad; it just doesn't refresh it.
3. /mcp → Reauthenticate fixes it without a full restart. The fact that this works means the auth flow itself is functional — Claude Code is simply not exercising the refresh token automatically.
4. All OAuth connectors disconnect together or independently — I haven't tracked precisely, but the pattern strongly suggests a shared token-refresh code path that fails system-wide.

Reproduction (best-effort)

This is hard to reproduce on demand because it appears random in time, but the following setup reliably reproduces it within a workday:

1. Add at least 2 remote OAuth-based MCP connectors (e.g. ClickUp, PostHog).
2. Run 2+ concurrent claude CLI sessions in different iTerm2 tabs.
3. Use the sessions normally over a few hours.
4. At some point — typically while one session is making tool calls — /mcp in any session will start showing connectors as failed.
5. /mcp → Reauthenticate on the affected connector restores it for that session.

This is consistent with the refresh-token race condition documented in #24317 (concurrent sessions trying to refresh the same OAuth token), even though that issue is marked closed.

Cache file is suggestive

~/.claude/mcp-needs-auth-cache.json exists and is populated with per-connector timestamps:

{
  "ClickUp": {"timestamp": <unix_ms>, "id": "mcpsrv_..."},
  "PostHog": {"timestamp": <unix_ms>},
  ...
}

This implies Claude Code knows when a connector's token needs refreshing — it's tracking the state — but the refresh isn't happening proactively. The token only gets renewed when the user manually triggers /mcp → Reauthenticate.

Hypotheses for the maintainers

Not having visibility into the source, but based on closed-issue context:

1. Refresh token isn't used at all in the silent-refresh path (mirrors #21333, #25245). Tokens are stored in Keychain / ~/.claude/.credentials.json but the code only uses the access token until expiry, then drops to failed without trying the refresh token.
2. Race between concurrent sessions corrupts the refresh token (mirrors #24317). Once corrupted, neither session can refresh; manual re-auth from the OAuth flow regenerates a valid pair.
3. Auto-locking duplicates after 7 days prevents users from re-reporting persistence, which keeps issue counters artificially low.

Asks

• Re-open #24317 (or treat this issue as its successor). The 2 dispute comments after the completed closure are evidence the fix didn't land for all users; auto-locking the issue means we have no channel back to the original thread.
• Document the refresh-token expectations in plugins/plugin-dev/skills/mcp-integration/references/authentication.md. Right now the doc covers the OAuth setup but says nothing about how Claude Code is supposed to keep tokens alive across long sessions or between sessions on the same machine.
• Stop closing duplicates as completed. Marking a known-painful, recurring issue as fixed-on-merge without verifying with the original reporters is what got us here.

Happy to provide logs (~/.claude/debug/, redacted), more reproduction details, or test a patched build.