feat: add needs_reauth state and replace per-user connection badge with sessions link

[Pratham-Mishra04]

Summary

Per-user auth clients (per_user_oauth and per_user_headers) don't hold a persistent upstream connection, so displaying a connection-state badge for them is misleading. This PR replaces that badge with a "View sessions" link pointing to the MCP Sessions table filtered by the client. It also adds proper handling for the needs_reauth state, which previously had no color mapping and no explanatory copy.

Changes

• Per-user auth clients now show a "View sessions" link instead of a connection-state badge in both the clients table and the client detail sheet, since their stateless design means connection state is not meaningful for them.
• The "Reconnect" action in the client actions menu is now disabled when a client is in the needs_reauth state, since reconnecting is not a valid recovery path for expired credentials.
• A needs_reauth color mapping (bg-red-100 text-red-800) has been added to MCP_STATUS_COLORS so the badge renders correctly for server-level clients in that state.
• A descriptive sheet subtitle is shown when a client is in the needs_reauth state, explaining that credentials have expired and that recreating the client is the current workaround.
• MCPConnectionState type has been extended to include needs_reauth.
• Documentation has been updated to explain why per-user clients show sessions instead of a connection state.

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

1. Create an MCP client with per_user_oauth or per_user_headers auth type.
2. Verify the clients table shows a "View sessions" link instead of a connection-state badge for that client.
3. Click the link and confirm it navigates to the MCP Sessions page filtered by that client's ID.
4. Open the client detail sheet and confirm the same "View sessions" link appears in the title area.
5. Create or simulate a server-level client in the needs_reauth state and confirm the badge renders in red and the sheet description explains the reauth requirement.
6. Confirm the "Reconnect" action is disabled for clients in the needs_reauth state.

cd ui
pnpm i || npm i
pnpm build || npm run build

Screenshots/Recordings

Before: Per-user auth clients displayed a connection-state badge (e.g., connected) that did not reflect their actual stateless behavior.

After: Per-user auth clients display a "View sessions" link. Server-level clients in needs_reauth show a red badge with an explanatory description.

Breaking changes

• No

Related issues

Security considerations

None. This is a display-layer change; no auth logic or credential handling was modified.

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 👈 (View in Graphite)
• 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
• 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 session links for per-user-authenticated MCP clients.
  • Added clear messaging when credentials require reauthorization, including guidance to recreate the client.

• Bug Fixes

  • Disabled reconnect actions for clients requiring reauthorization.
  • Added visual support for the “Needs reauthorization” status.

• Documentation

  • Clarified how connection states and MCP sessions apply to server-level and per-user clients.

Walkthrough

Per-user MCP clients now link to MCP sessions instead of shared connection states. The MCP status model adds needs_reauth for expired credentials, with matching styling, reconnect restrictions, client-sheet messaging, and documentation updates.

Changes

MCP session status handling

Layer / File(s)	Summary
Reauthentication status presentation ui/lib/types/mcp.ts, ui/lib/constants/config.ts, ui/app/workspace/mcp-registry/views/mcpClientSheet.tsx	Adds the needs_reauth status, applies error styling, and explains expired credentials and the current recreation workaround.
Clients table status actions ui/app/workspace/mcp-registry/views/mcpClientsTable.tsx	Disables reconnect for needs_reauth clients. Per-user-authenticated clients link to filtered sessions instead of displaying connection-state badges.
Authentication documentation docs/mcp/auth/overview.mdx	Defines connection-state semantics for persistent server-level clients and session navigation for stateless per-user clients.

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

Possibly related issues

• maximhq/bifrost#5028 — Adds the related MCP needs_reauth state and expired credential handling.

Possibly related PRs

• maximhq/bifrost#5712 — Directly relates to the needs_reauth state surfaced by this PR.
• maximhq/bifrost#5716 — Modifies needs_reauth behavior in the same registry views.
• maximhq/bifrost#5722 — Updates MCP authentication documentation for needs_reauth.

Suggested reviewers: akshaydeo, danpiths, bearts

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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 and concisely summarizes both primary changes: adding the needs_reauth state and replacing per-user connection badges with a sessions link.
Description check	✅ Passed	The description covers the purpose, changes, affected areas, testing steps, breaking changes, security, and documentation updates, with only optional links or recordings absent.

✨ Finishing Touches 💡 1

📝 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_surface_needs_reauth_state_in_the_mcp_client_ui

---

_{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:18 AM UTC: Graphite rebased this pull request as part of a merge.
• Aug 8, 9:19 AM UTC: @Pratham-Mishra04 merged this pull request with Graphite.

The base branch was changed.