feat: retain admin bootstrap credential for periodic per-user MCP tool discovery refresh

[Pratham-Mishra04]

Summary

Per-user MCP clients (per_user_oauth and per_user_headers) never hold a persistent connection, so the periodic tool syncer was silently skipping them entirely — their tool lists could never be refreshed after initial bootstrap. This PR introduces an "admin credential" retention mechanism: the bootstrap-verification credential (OAuth token or header values) submitted by the admin during one-time setup is now persisted under auth_mode='admin' and reused by the tool syncer to run ephemeral connect-discover-close cycles, keeping per-user clients' tool lists up to date without requiring a real end-user request.

Changes

• Admin credential retention at bootstrap time: completeMCPClientOAuth now re-tags the admin's bootstrap OAuth token from auth_mode='shared' to auth_mode='admin' (instead of revoking it) after a successful verification. verifyMCPClientHeaders now persists the admin's sample header values as an auth_mode='admin' credential row. Both are best-effort — a retention failure does not fail the request.

• performAdminToolDiscovery on MCPManager: New method that resolves the retained admin credential via credStore.AdminConnectionHeaders and runs a one-shot ephemeral connect-discover-close cycle using the same VerifyPerUserOAuthConnection / VerifyHeadersConnection functions the bootstrap flow uses.

• ClientToolSyncer.performSync widened: The conn == nil branch now distinguishes per-user auth types (per_user_oauth, per_user_headers) from shared-connection types. Per-user clients with no live conn are routed into performAdminToolDiscovery instead of being silently skipped; shared-connection clients mid-reconnect continue to be skipped as before.

• AdminConnectionHeaders added to MCPCredentialStore interface and all resolvers: per_user_oauth and per_user_headers resolvers implement it meaningfully (OAuth token lookup via GetAdminAccessToken; header credential lookup via GetCredentialByMode with MCPAuthModeAdmin). All shared-credential resolvers (none, headers, oauth) return an explicit unsupported error.

• GetAdminAccessToken added to OAuth2Provider: Resolves the auth_mode='admin' token row via GetAdminOauthTokenByConfigID and funnels it through the extracted resolveAccessToken helper (shared with GetAccessToken to avoid duplicating status/expiry/refresh/sanitize logic).

• TokenRefreshWorker default AuthModes widened to ["shared", "admin"]: Admin-mode tokens back only the tool syncer and have no live caller to trigger lazy refresh, so they need the same proactive background sweep as shared tokens.

• MCPAuthModeAdmin support in GetMCPPerUserHeaderCredentialByMode and UpsertMCPPerUserHeaderCredential: Admin-mode rows are scoped by mcp_client_id alone (no per-caller identity). The identity guard in mcp_headers.Provider.GetCredentialByMode is widened to allow an empty identity for MCPAuthModeAdmin only.

• Database migration add_mcp_admin_auth_mode_indexes: Adds partial unique indexes on mcp_oauth_tokens and mcp_per_user_header_credentials for auth_mode='admin', enforcing exactly one admin credential per MCP client.

• UI copy updates: Admin bootstrap flows for both OAuth and headers now accurately describe that the credential is retained for periodic tool-list refresh rather than discarded after a one-time test.

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

# Core/Transports
go test ./core/mcp/... ./core/schemas/... ./framework/configstore/... ./framework/mcp_headers/... ./framework/oauth2/... ./transports/bifrost-http/...

# UI
cd ui
pnpm i
pnpm build

• Bootstrap a per_user_oauth MCP client through the admin OAuth flow and confirm the token row in mcp_oauth_tokens has auth_mode='admin' after completion.
• Bootstrap a per_user_headers MCP client and confirm a row with auth_mode='admin' appears in mcp_per_user_header_credentials.
• Wait for or manually trigger a tool-sync cycle and confirm the per-user client's tool list is updated (previously it would be silently skipped).
• Confirm shared-connection clients (headers, none, oauth) with conn == nil (mid-reconnect) are still silently skipped and not routed into admin discovery.

Breaking changes

• Yes
• No

MCPCredentialStore and OAuth2Provider are interfaces with new required methods (AdminConnectionHeaders and GetAdminAccessToken respectively). Any external implementations of these interfaces must add stub or real implementations of these methods. The ConfigStore interface also gains GetAdminOauthTokenByConfigID. The TokenRefreshWorker default AuthModes changes from ["shared"] to ["shared", "admin"], which may cause additional token refresh queries if admin-mode rows exist.

Security considerations

The retained admin credential (auth_mode='admin') is used exclusively by the internal tool syncer for tool-list discovery — it is never injected into real end-user requests. The per_user_oauth resolver's AdminConnectionHeaders and the per_user_headers resolver's AdminConnectionHeaders both enforce this separation at the resolver level. The partial unique indexes ensure at most one admin credential exists per MCP client, preventing accumulation of stale bootstrap credentials.

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 👈 (View in Graphite)
• 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
• 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 automatic tool discovery and periodic tool-list refresh for per-user OAuth and header-authenticated MCP connections, including connections without persistent sessions.
  • Retained successfully verified administrator credentials to support ongoing updates.

• Bug Fixes

  • Improved handling of expired, missing, invalid, and unsupported credentials.
  • Preserved existing tools when refresh or discovery fails.

• Documentation

  • Clarified sign-in, credential retention, and tool discovery behavior in setup messages.

Walkthrough

The change retains admin credentials for per-user MCP clients. Credential stores resolve OAuth bearer headers or filtered headers. Disconnected per-user clients use these credentials for tool discovery. Storage, token refresh, synchronization, tests, and UI copy support the flow.

Changes

Admin MCP discovery flow

Layer / File(s)	Summary
Admin credential contracts and storage core/schemas/*, framework/configstore/..., framework/mcp_headers/*	Adds admin-mode contracts, client-scoped credential lookup, uniqueness indexes, and upsert behavior.
Admin OAuth resolution and refresh framework/oauth2/*, framework/configstore/*	Adds admin token resolution and includes admin tokens in proactive refresh.
Admin connection-header resolvers core/mcp/credstore/*, core/mcp/auth_retry_test.go, core/mcp/reauth_state_test.go	Resolves retained OAuth bearer headers and filtered per-user headers. Unsupported modes return errors.
Verification retention transports/bifrost-http/handlers/mcp.go, transports/bifrost-http/lib/config_test.go, ui/app/workspace/mcp-registry/views/*	Stores successful admin OAuth credentials or canonicalized headers. Supporting mocks and UI copy describe periodic tool refreshes.
Admin discovery and synchronization core/mcp/clientmanager.go, core/mcp/toolsync.go, core/mcp/*_test.go	Disconnected per-user clients perform credential-backed discovery. Tests cover success, fail-fast errors, unsupported modes, credential failures, and tool preservation.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant performSync
  participant performAdminToolDiscovery
  participant MCPCredentialStore
  participant MCPServer
  performSync->>performAdminToolDiscovery: discover tools for disconnected per-user client
  performAdminToolDiscovery->>MCPCredentialStore: resolve retained admin headers
  performAdminToolDiscovery->>MCPServer: verify connection and request tools
  MCPServer-->>performSync: return discovered tool mappings

Loading

Possibly related issues

• [Bug]: Insufficient fix for #4314, /mcp gateway still serves 0 tools after restart and reconnect because the tool registry is never resynced #4998: The issue identifies performSync as a tool-state update path that can leave the gateway registry stale.

Possibly related PRs

• maximhq/bifrost#5716: Both add admin-mode OAuth credentials and modify MCP OAuth handling.
• maximhq/bifrost#5718: Both modify retained per-user MCP credentials and discovery flows.
• maximhq/bifrost#5727: Both modify MCP tool synchronization through core/mcp/toolsync.go.

Suggested reviewers: akshaydeo, danpiths, bearts

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 84.38% 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 and concisely summarizes retaining admin bootstrap credentials for periodic per-user MCP tool discovery.
Description check	✅ Passed	The description follows the template and covers purpose, changes, testing, affected areas, breaking changes, security, and checklist items.

✨ 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-30-feat_retain_admin_bootstrap_credential_for_per-user_mcp_tool_discovery

---

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

[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 `@framework/oauth2/access_token_test.go`:
- Around line 165-176: Update TestAccessToken_MissingToken_ReturnsError to seed
an active token linked to the same OAuth configuration but using the opposite
auth_mode for each getter case, while leaving the requested mode without a
token. Keep the existing missing-token assertions so the test verifies
credentials are isolated between shared and admin modes.

🪄 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: a8939b97-5c43-4461-9205-fbbc3938a474

📥 Commits

Reviewing files that changed from the base of the PR and between 2fc7ca2 and ef71e78.

📒 Files selected for processing (37)

• core/mcp/admin_tool_discovery_test.go
• core/mcp/auth_retry_test.go
• core/mcp/clientmanager.go
• core/mcp/credstore/credstore.go
• core/mcp/credstore/none.go
• core/mcp/credstore/none_test.go
• core/mcp/credstore/per_user_headers.go
• core/mcp/credstore/per_user_headers_test.go
• core/mcp/credstore/per_user_oauth.go
• core/mcp/credstore/per_user_oauth_test.go
• core/mcp/credstore/shared_headers.go
• core/mcp/credstore/shared_headers_test.go
• core/mcp/credstore/shared_oauth.go
• core/mcp/credstore/shared_oauth_test.go
• core/mcp/reauth_state_test.go
• core/mcp/toolsync.go
• core/mcp/toolsync_test.go
• core/schemas/mcp.go
• core/schemas/oauth.go
• framework/configstore/migrations.go
• framework/configstore/rdb.go
• framework/configstore/rdb_mcp_admin_auth_mode_test.go
• framework/configstore/store.go
• framework/configstore/tables/mcpheaders.go
• framework/configstore/tables/mcpoauth2.go
• framework/mcp_headers/credential_test.go
• framework/mcp_headers/main.go
• framework/mcp_headers/main_test.go
• framework/oauth2/access_token_test.go
• framework/oauth2/main.go
• framework/oauth2/sync.go
• framework/oauth2/sync_test.go
• transports/bifrost-http/handlers/mcp.go
• transports/bifrost-http/lib/config_test.go
• ui/app/workspace/mcp-registry/views/mcpClientSheet.tsx
• ui/app/workspace/mcp-registry/views/mcpHeadersAuthorizer.tsx
• ui/app/workspace/mcp-registry/views/oauth2Authorizer.tsx

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

• ui/app/workspace/mcp-registry/views/mcpClientSheet.tsx
• framework/oauth2/sync_test.go
• core/mcp/clientmanager.go
• core/mcp/reauth_state_test.go
• core/mcp/toolsync.go
• core/schemas/mcp.go
• framework/configstore/rdb.go
• core/mcp/credstore/none_test.go
• transports/bifrost-http/lib/config_test.go
• ui/app/workspace/mcp-registry/views/oauth2Authorizer.tsx
• core/schemas/oauth.go
• core/mcp/credstore/shared_oauth_test.go
• transports/bifrost-http/handlers/mcp.go
• core/mcp/credstore/per_user_oauth_test.go
• core/mcp/credstore/shared_headers.go
• framework/configstore/tables/mcpoauth2.go
• framework/mcp_headers/main.go
• core/mcp/credstore/credstore.go
• core/mcp/credstore/per_user_headers_test.go
• core/mcp/admin_tool_discovery_test.go
• core/mcp/toolsync_test.go
• core/mcp/credstore/shared_headers_test.go
• framework/configstore/tables/mcpheaders.go
• framework/configstore/store.go
• core/mcp/credstore/none.go
• framework/configstore/migrations.go
• core/mcp/auth_retry_test.go
• ui/app/workspace/mcp-registry/views/mcpHeadersAuthorizer.tsx
• framework/oauth2/main.go
• framework/mcp_headers/main_test.go
• core/mcp/credstore/shared_oauth.go
• core/mcp/credstore/per_user_oauth.go

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

🧹 Nitpick comments (1)

framework/configstore/rdb_mcp_admin_auth_mode_test.go (1)

22-31: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Remove manual GORM timestamp initialization.

GORM populates CreatedAt and UpdatedAt during Create. These tests do not assert the supplied values. Remove now, the timestamp fields, and the unused time import.

Based on learnings: models with GORM automatic timestamp fields must rely on GORM rather than time.Now().

Also applies to: 56-61

🤖 Prompt for 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.

In `@framework/configstore/rdb_mcp_admin_auth_mode_test.go` around lines 22 - 31,
Remove the manual now := time.Now() setup and the CreatedAt and UpdatedAt
assignments from both TableMCPOauthToken fixtures in the test setup. Delete the
now-unused time import and rely on GORM's automatic timestamps during Create.

Source: Learnings

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

Nitpick comments:
In `@framework/configstore/rdb_mcp_admin_auth_mode_test.go`:
- Around line 22-31: Remove the manual now := time.Now() setup and the CreatedAt
and UpdatedAt assignments from both TableMCPOauthToken fixtures in the test
setup. Delete the now-unused time import and rely on GORM's automatic timestamps
during Create.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 264b663f-be07-45a0-8e18-8396c29cf28f

📥 Commits

Reviewing files that changed from the base of the PR and between bd1f787 and 97de528.

📒 Files selected for processing (37)

• core/mcp/admin_tool_discovery_test.go
• core/mcp/auth_retry_test.go
• core/mcp/clientmanager.go
• core/mcp/credstore/credstore.go
• core/mcp/credstore/none.go
• core/mcp/credstore/none_test.go
• core/mcp/credstore/per_user_headers.go
• core/mcp/credstore/per_user_headers_test.go
• core/mcp/credstore/per_user_oauth.go
• core/mcp/credstore/per_user_oauth_test.go
• core/mcp/credstore/shared_headers.go
• core/mcp/credstore/shared_headers_test.go
• core/mcp/credstore/shared_oauth.go
• core/mcp/credstore/shared_oauth_test.go
• core/mcp/reauth_state_test.go
• core/mcp/toolsync.go
• core/mcp/toolsync_test.go
• core/schemas/mcp.go
• core/schemas/oauth.go
• framework/configstore/migrations.go
• framework/configstore/rdb.go
• framework/configstore/rdb_mcp_admin_auth_mode_test.go
• framework/configstore/store.go
• framework/configstore/tables/mcpheaders.go
• framework/configstore/tables/mcpoauth2.go
• framework/mcp_headers/credential_test.go
• framework/mcp_headers/main.go
• framework/mcp_headers/main_test.go
• framework/oauth2/access_token_test.go
• framework/oauth2/main.go
• framework/oauth2/sync.go
• framework/oauth2/sync_test.go
• transports/bifrost-http/handlers/mcp.go
• transports/bifrost-http/lib/config_test.go
• ui/app/workspace/mcp-registry/views/mcpClientSheet.tsx
• ui/app/workspace/mcp-registry/views/mcpHeadersAuthorizer.tsx
• ui/app/workspace/mcp-registry/views/oauth2Authorizer.tsx

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

• core/mcp/auth_retry_test.go
• core/mcp/clientmanager.go
• core/mcp/credstore/per_user_headers_test.go
• framework/configstore/tables/mcpheaders.go
• framework/configstore/tables/mcpoauth2.go
• ui/app/workspace/mcp-registry/views/mcpHeadersAuthorizer.tsx
• framework/configstore/rdb.go
• core/mcp/credstore/shared_oauth.go
• core/mcp/credstore/per_user_oauth.go
• transports/bifrost-http/lib/config_test.go
• framework/oauth2/sync_test.go
• core/schemas/oauth.go
• core/mcp/reauth_state_test.go
• framework/configstore/store.go
• framework/mcp_headers/main.go
• core/mcp/credstore/none.go
• core/mcp/credstore/shared_headers_test.go
• core/mcp/credstore/shared_headers.go
• core/mcp/credstore/none_test.go
• framework/oauth2/main.go
• core/mcp/credstore/per_user_headers.go
• core/mcp/credstore/shared_oauth_test.go
• core/mcp/toolsync_test.go
• core/schemas/mcp.go
• core/mcp/admin_tool_discovery_test.go
• framework/mcp_headers/main_test.go
• transports/bifrost-http/handlers/mcp.go
• core/mcp/credstore/credstore.go
• core/mcp/credstore/per_user_oauth_test.go
• framework/configstore/migrations.go
• core/mcp/toolsync.go
• ui/app/workspace/mcp-registry/views/mcpClientSheet.tsx
• ui/app/workspace/mcp-registry/views/oauth2Authorizer.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, 9:27 AM UTC: Graphite rebased this pull request as part of a merge.
• Aug 8, 9:28 AM UTC: @Pratham-Mishra04 merged this pull request with Graphite.

The base branch was changed.