feat: add NeedsReauth MCP connection state for dead OAuth2 credentials

[Pratham-Mishra04]

Summary

When a shared-connection MCP client's OAuth2 credential permanently dies (refresh token rejected or expired), the client was being left in the generic Disconnected state. This is misleading because no amount of automatic reconnection will fix it — only a human reauthorizing the client will. This PR introduces a new NeedsReauth connection state that is set when connectToMCPClient detects an ErrOAuth2TokenExpired-wrapped failure, and ensures the health monitor does not silently overwrite it with Connected or Disconnected during subsequent ping cycles.

Changes

• Added MCPConnectionStateNeedsReauth to the MCPConnectionState enum in schemas/mcp.go, with documentation distinguishing it from PendingVerification and noting it only applies to shared-connection auth types.
• In connectToMCPClient, after a gate error is returned, the error string is checked against ErrOAuth2TokenExpired using the new isOAuth2TokenExpiredErrorText helper. If matched, the client state is flipped to NeedsReauth under the manager lock, mirroring how the success path sets Connected.
• In EnableClient, the post-connect failure state update was changed from an if/else to a switch so that NeedsReauth (already written by connectToMCPClient under its own lock) is preserved rather than overwritten with Disconnected.
• In updateClientState on the health monitor, the existing Disabled guard was extended to also bail out early for NeedsReauth, preventing health-check ticks from clobbering the more specific signal.
• Added isOAuth2TokenExpiredErrorText in utils.go, using the same substring-matching technique as isTransientError because runConnectWithPluginPipeline flattens the underlying Go error to a string on the BifrostError it returns, making errors.Is/errors.As unusable at the call site.
• Added reauth_state_test.go covering: the isOAuth2TokenExpiredErrorText helper, the connectToMCPClient path that sets NeedsReauth on OAuth expiry, the control case that generic failures stay Disconnected, the health monitor guard that preserves NeedsReauth against both failed and successful ping ticks, and a regression guard confirming the pre-existing Disabled preservation behavior is unchanged.

Type of change

• Bug fix
• Feature
• Refactor
• Documentation
• Chore/CI

Affected areas

• Core (Go)
• Transports (HTTP)
• Providers/Integrations
• Plugins
• UI (React)
• Docs

How to test

go version
go test ./core/mcp/...

The new reauth_state_test.go file covers the primary scenarios:

1. A client whose OAuth credential store returns an ErrOAuth2TokenExpired-wrapped error on ConnectionHeaders should land in MCPConnectionStateNeedsReauth after connectToMCPClient returns.
2. A client whose credential store returns a plain connectivity error should remain in MCPConnectionStateDisconnected.
3. A client already in NeedsReauth should not be moved to Connected or Disconnected by health monitor ticks.
4. A client in Disabled should still be unaffected by health monitor ticks (regression guard).

Breaking changes

• No

The new needs_reauth state string is additive. Existing clients in Disconnected, Disabled, or other states are unaffected.

Security considerations

This change improves visibility into dead OAuth2 credentials by surfacing them as a distinct state rather than silently retrying forever. No secrets or PII are exposed; the state transition is based solely on error text matching against a known sentinel error string.

Checklist

• I read docs/contributing/README.md and followed the guidelines
• I added/updated tests where appropriate
• I updated documentation where needed
• I verified builds succeed (Go and UI)
• I verified the CI pipeline passes locally if applicable

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[Pratham-Mishra04]

• feat: add stack-absorb Claude skill for manual Graphite stack change distribution #5786 : 2 dependent PRs (#5787 , #5812 )
• docs+feat: expand MCP connection states into reference table and add tooltip to State column header #5785
• feat: add token-exchange demo MCP server for testing against real identity providers #5730
• docs: add token exchange (on-behalf-of) MCP auth documentation #5729
• docs: document make-before-break reconnection and shared-client retry behavior #5728
• feat: make-before-break reconnect for HTTP/SSE MCP clients with generation-guarded stale write protection #5727
• feat: retry shared-connection MCP auth failures after bounded reconnect wait with concurrent dedup #5726
• feat: add ui for token_exchange (On-Behalf-Of) auth type MCP clients #5725
• feat: add token_exchange MCP auth type with delegated identity-provider token exchange #5724
• docs: add needs_reauth state, reauthorize endpoint, per-client tool sync/timeout, allowed_extra_headers, and OAuth config rotation to MCP OpenAPI spec #5723
• docs: add OAuth reauthorization, admin discovery credentials, auth failure recovery, and credential rotation docs #5722
• docs: add env./vault. reference support for OAuth client_id/client_secret and update OpenAPI EnvVar schema #4860
• docs: add pending_verification state and initiate-verification / verify-headers MCP client endpoints to OpenAPI spec #4858
• docs: add config.json bootstrap support for auth-aware MCP clients (oauth, per_user_oauth, per_user_headers) #3876
• feat: use *SecretVar for OAuth2Config credentials to preserve env./vault. #4859
• feat: add LRU credential cache to MCP headers provider with scoped eviction #5721
• feat: add in-memory LRU cache for per-user MCP OAuth access tokens with targeted eviction #5720
• feat: add generation-guarded LRU cache with single-flight fills and secondary index #5719
• feat: add per-user OAuth/headers admin discovery credential repair flow with registry needs_reauth projection #5718
• feat: retain admin bootstrap credential for periodic per-user MCP tool discovery refresh #5717
• feat: add MCPAuthModeAdmin + reauthorize endpoint for shared OAuth MCP clients #5716
• feat: replace OAuth config pin-and-warn with in-place rotation and needs_reauth cascade #5715
• feat: add needs_reauth state and replace per-user connection badge with sessions link #5714
• feat: add auth-failure retry with forced credential refresh for MCP tool calls #5713
• feat: add NeedsReauth MCP connection state for dead OAuth2 credentials #5712 👈 (View in Graphite)
• refactor: make GetExpiringOauthTokens auth modes caller-configurable via AuthModes field #5711
• refactor: unify shared and per-user OAuth refresh under a single RefreshAccessToken(tokenID) path, dropping oauth_configs.token_id FK shortcut #5710
• refactor: migrate OAuth flow state/PKCE fields from oauth_configs to new mcp_oauth_flows table #5709
• refactor: merge oauth_tokens/oauth_user_tokens into unified mcp_oauth_tokens table #5708
• feat: add per_user_headers bootstrap verification flow via submitHandler abstraction #3875
• feat: add verify-headers endpoint and pending_verification state for per-user-headers MCP clients #3874
• fix: extend pending_verification bootstrap path to cover per_user_oauth clients #3873
• feat: add OAuth authorization flow for config.json-bootstrapped pending_verification MCP clients #3872
• feat: add pending_verification state and initiate-verification endpoint for config.json shared-OAuth MCP clients #3871
• docs: document flow mode access rules, temp token toggle, and per-server tool manager overrides #3870 : 1 other dependent PR (#3882 )
• dev

This stack of pull requests is managed by Graphite. Learn more about stacking.

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Added a distinct connection status for shared integrations that require OAuth reauthorization.
  • Expired OAuth credentials are now identified and surfaced as requiring reauthorization.

• Bug Fixes

  • Prevented health checks and reconnection attempts from overwriting “Needs reauthorization” or “Disabled” statuses.
  • Preserved the reauthorization status when reconnection fails.
  • Kept unrelated connection failures marked as disconnected.
  • Ignored stale connection events for disabled or reauthorization-required integrations.

Walkthrough

Shared MCP connections now expose needs_reauth when OAuth credentials permanently expire. Connection failures and health checks preserve this state. Generic failures remain Disconnected, and disabled clients remain Disabled.

Changes

MCP reauthentication lifecycle

Layer / File(s)	Summary
Reauthentication state and expiration detection core/schemas/mcp.go, core/mcp/utils.go, core/mcp/reauth_state_test.go	Adds the needs_reauth state and detects OAuth token-expiration errors in flattened connection errors.
Connection failure state transitions core/mcp/clientmanager.go, core/mcp/reauth_state_test.go	Marks expired OAuth connections as NeedsReauth, preserves disabled clients, ignores stale SSE callbacks, and keeps generic failures disconnected.
Health-monitor state preservation core/mcp/healthmonitor.go, core/mcp/reauth_state_test.go	Prevents health checks and reconnect attempts from overwriting NeedsReauth or Disabled. Tests cover both states.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant OAuthCredentialStore
  participant connectToMCPClient
  participant MCPClientManager
  OAuthCredentialStore->>connectToMCPClient: return expired OAuth credential error
  connectToMCPClient->>MCPClientManager: report connection failure
  MCPClientManager->>MCPClientManager: set NeedsReauth

Loading

Possibly related PRs

• maximhq/bifrost#5714: Adds UI behavior for the needs_reauth state introduced by this backend flow.
• maximhq/bifrost#5715: Modifies the same MCP state handling and reauthentication behavior.
• maximhq/bifrost#5718: Extends the MCPConnectionStateNeedsReauth semantics defined by this change.

Suggested reviewers: akshaydeo, danpiths, roroghost17

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 87.50% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the main change: adding the NeedsReauth MCP state for expired OAuth2 credentials.
Description check	✅ Passed	The description explains the problem, implementation, tests, affected area, security impact, and breaking-change status; optional checklist items remain unchecked.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 07-29-feat_add_mcpconnectionstateneedsreauth_for_shared_mcp_clients

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[Pratham-Mishra04]

Merge activity

• Aug 8, 8:47 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• Aug 8, 9:12 AM UTC: Graphite rebased this pull request as part of a merge.
• Aug 8, 9:13 AM UTC: @Pratham-Mishra04 merged this pull request with Graphite.

The base branch was changed.