feat: add OAuth authorization flow for config.json-bootstrapped pending_verification MCP clients

[Pratham-Mishra04]

Summary

MCP clients declared via config.json can be bootstrapped into a pending_verification state that requires a one-time OAuth authorization before they can be used. Previously, there was no way to complete this authorization from the UI. This PR adds an Authorize button to the MCP client detail sheet for clients in the pending_verification state, which triggers the same OAuth2 popup flow used during UI-based client creation.

Changes

• Added initiateMCPClientVerification API mutation that calls POST /mcp/client/:id/initiate-verification, returning an OAuthFlowResponse with an authorize_url and oauth_config_id.
• Added pending_verification to the MCPConnectionState type and its corresponding badge color (bg-yellow-100 text-yellow-800).
• In MCPClientSheet, when a client is in pending_verification state and the user has update access, an Authorize button is shown in the sheet header. Clicking it calls initiate-verification and opens the OAuth2Authorizer dialog on success.
• The sheet description is contextually updated for pending_verification clients to explain that a one-time OAuth authorization is required.
• The sheet's close handler is guarded against closing while the bootstrap OAuth dialog is open.

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. Bootstrap an MCP client via config.json with an OAuth-based server so it lands in pending_verification state.
2. Open the MCP Registry in the UI and click on the client.
3. Verify the sheet header shows the pending_verification badge and an Authorize button.
4. Verify the sheet description reads: "This client was declared in config.json and needs a one-time OAuth authorization before it can be used."
5. Click Authorize and confirm the OAuth popup opens.
6. Complete the OAuth flow and verify the client transitions out of pending_verification and the sheet closes.

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

Screenshots/Recordings

Add before/after screenshots of the MCP client sheet in pending_verification state.

Breaking changes

• No

Related issues

Security considerations

The Authorize button is gated behind RbacResource.MCPGateway / RbacOperation.Update access, ensuring only authorized admins can initiate the OAuth verification flow for config-bootstrapped clients.

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

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• New Features
  • Added OAuth authorization for MCP clients requiring verification.
  • Added an Authorize action with progress feedback and automatic status refresh.
  • Added support for the new Pending verification connection status.
  • Updated status styling to clearly identify clients awaiting verification.
  • Added contextual guidance when authorization is pending.

Walkthrough

Adds the pending_verification MCP state, a verification-initiation mutation, and table actions that launch and complete bootstrap OAuth authorization. The client sheet adds a conditional authorization description and formatting updates.

Changes

Bootstrap OAuth Verification Flow

Layer / File(s)	Summary
Verification state and API contract ui/lib/types/mcp.ts, ui/lib/constants/config.ts, ui/lib/store/apis/mcpApi.ts	Adds pending_verification, yellow status styling, and the verification response type, mutation, and generated hook.
Table authorization flow ui/app/workspace/mcp-registry/views/mcpClientsTable.tsx	Adds the Authorize action, verification request handling, authorization progress state, OAuth2Authorizer integration, completion callbacks, and client refresh behavior.
OAuth popup reuse ui/app/workspace/mcp-registry/views/oauth2Authorizer.tsx	Allows the authorizer to reuse the synchronously opened popup once and to open new popups for later attempts.
Client sheet updates ui/app/workspace/mcp-registry/views/mcpClientSheet.tsx	Adds the virtual-key query import, a pending-verification description, and formatting updates to TLS mappings, fallback literals, handlers, and header parsing.

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

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant MCPClientsTable
  participant mcpApi
  participant OAuth2Authorizer

  User->>MCPClientsTable: Select Authorize
  MCPClientsTable->>mcpApi: initiateMCPClientVerification(client_id)
  mcpApi-->>MCPClientsTable: OAuth verification details
  MCPClientsTable->>OAuth2Authorizer: Reuse or open OAuth popup
  OAuth2Authorizer-->>MCPClientsTable: Success or error callback
  MCPClientsTable->>MCPClientsTable: Refresh MCP clients after success

Loading

Possibly related PRs

• maximhq/bifrost#3871: Implements related MCP client support for pending_verification and the verification endpoint.
• maximhq/bifrost#3873: Modifies the same MCP client bootstrap OAuth flow and table component.
• maximhq/bifrost#3875: Shares pending_verification handling in the MCP client table and related verification flow.

Suggested reviewers: akshaydeo, danpiths, roroghost17

🚥 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 identifies the OAuth authorization feature for config.json-bootstrapped pending_verification MCP clients.
Description check	✅ Passed	The description covers the purpose, changes, testing steps, affected areas, security, and breaking changes, with only minor checklist and screenshot gaps.

✨ 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 05-29-feat_ui_support_for_pending_auth_mcps

---

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

[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
• 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 👈 (View in Graphite)
• 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.

[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.}

[greptile-apps]

Confidence Score: 5/5

This looks safe to merge.

• Verification initiation failures now display destructive toasts.
• Unexpected successful response shapes also display an error.
• No blocking issue remains in the updated flow.

Important Files Changed

Filename	Overview
ui/app/workspace/mcp-registry/views/mcpClientSheet.tsx	Adds the authorization action, OAuth dialog lifecycle, contextual description, and user-facing initiation errors.
ui/app/workspace/mcp-registry/views/mcpClientsTable.tsx	Disables reconnect for clients awaiting OAuth verification.
ui/lib/store/apis/mcpApi.ts	Adds and exports the client verification initiation mutation.
ui/lib/types/mcp.ts	Adds pending verification to the MCP connection state.
ui/lib/constants/config.ts	Adds badge styling for the pending verification state.

_{Reviews (6): Last reviewed commit: "feat: ui support for pending auth mcps" | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@ui/app/workspace/mcp-registry/views/mcpClientSheet.tsx`:
- Around line 90-103: The handleStartBootstrap flow only logs failures, so a
failed verification start leaves the user with no feedback and no dialog. Update
the catch path in mcpClientSheet.tsx to surface a user-visible error (for
example via the existing useToast hook) when initiateVerification(...).unwrap()
fails, and keep the behavior limited to showing the error without opening the
bootstrap dialog. Also remove the later duplicate const { toast } = useToast()
so mcpClientSheet uses a single toast declaration.

In `@ui/lib/store/apis/mcpApi.ts`:
- Around line 239-244: The initiateMCPClientVerification mutation is typed with
the wrong response contract, so adjust the response type to match the backend
payload instead of OAuthFlowResponse. Update the type used in mcpApi.ts for
initiateMCPClientVerification to reflect the initiate-verification response
shape that includes status_url and does not require message, and rename or
introduce a dedicated type if needed so any consumers cannot safely access
response.message when it is not guaranteed.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 30fdee05-60a6-48e6-8abe-22d400771510

📥 Commits

Reviewing files that changed from the base of the PR and between f63648d and 41d8011.

📒 Files selected for processing (4)

• ui/app/workspace/mcp-registry/views/mcpClientSheet.tsx
• ui/lib/constants/config.ts
• ui/lib/store/apis/mcpApi.ts
• ui/lib/types/mcp.ts

[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.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@ui/app/workspace/mcp-registry/views/oauth2Authorizer.tsx`:
- Around line 129-132: Update the initial popup initialization flow around
initialPopupConsumedRef and the auto-open effect to tolerate React Strict Mode
replay: preserve the user-activated initialPopup instead of closing or consuming
it during the replay, and ensure initialization runs only once per authorization
attempt. Also reset or replace the attempt state when authorization changes so a
newly opened popup is not ignored while the component remains mounted.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: e89eff65-3f76-4b51-ae32-78962bbcb231

📥 Commits

Reviewing files that changed from the base of the PR and between 78aaeec and fd4d929.

📒 Files selected for processing (6)

• ui/app/workspace/mcp-registry/views/mcpClientSheet.tsx
• ui/app/workspace/mcp-registry/views/mcpClientsTable.tsx
• ui/app/workspace/mcp-registry/views/oauth2Authorizer.tsx
• ui/lib/constants/config.ts
• ui/lib/store/apis/mcpApi.ts
• ui/lib/types/mcp.ts

🚧 Files skipped from review as they are similar to previous changes (5)

• ui/lib/types/mcp.ts
• ui/lib/constants/config.ts
• ui/app/workspace/mcp-registry/views/mcpClientSheet.tsx
• ui/lib/store/apis/mcpApi.ts
• ui/app/workspace/mcp-registry/views/mcpClientsTable.tsx

[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, 8:50 AM UTC: Graphite rebased this pull request as part of a merge.
• Aug 8, 8:51 AM UTC: @Pratham-Mishra04 merged this pull request with Graphite.

The base branch was changed.