feat: add mcp_server_auth_mode and OAuth 2.1 gateway auth docs with gateway-auth page

[Pratham-Mishra04]

Summary

Adds a new mcp/gateway-auth.mdx documentation page covering how inbound MCP clients authenticate to Bifrost's /mcp endpoint, and introduces the mcp_server_auth_mode configuration field (headers, both, oauth) along with an oauth2_server_config block for controlling Bifrost's OAuth 2.1 authorization server behavior.

Changes

• New mcp/gateway-auth.mdx page — documents the three auth modes, the full OAuth 2.1 connect flow (with sequence diagram), identity modes at consent (virtual key, session, user), configuration via UI/API/config.json, grant management, token lifetime and revocation behavior, discovery endpoints, and troubleshooting guidance.
• mcp_server_auth_mode and oauth2_server_config fields — added to the OpenAPI schema and config YAML. mcp_server_auth_mode controls whether /mcp accepts header credentials, Bifrost-issued JWTs, or both. oauth2_server_config exposes issuer_url, auth_code_ttl, and access_token_ttl.
• mcp_external_base_url renamed to mcp_external_client_url — clarifies that this field governs Bifrost's outbound OAuth client redirect URI (to upstream servers like Notion/Jira), not the inbound server-side discovery URL.
• mcp/gateway.mdx updated — the per-user auth section now references the gateway auth mode and notes that identity establishment differs between headers and both/oauth modes. The Claude Code DCR probe note is updated to reflect that in both/oauth mode the probe is handled correctly and the error doesn't appear.
• cli-agents/claude-code.mdx updated — the "Method Not Allowed" troubleshooting note is scoped to the default headers mode and clarifies that both/oauth mode serves real Dynamic Client Registration.
• docs.json updated — mcp/gateway-auth added to the MCP Gateway navigation group; indentation normalized to tabs throughout.
• New UI screenshots — ui-mcp-server-auth-mode.png, ui-oauth-consent.png, and ui-oauth-grants.png added.

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

Navigate to the MCP Gateway section of the docs and verify the new Gateway Authentication page renders correctly, including the sequence diagram, configuration tabs, and screenshots. Confirm the mcp/gateway.mdx cross-links to gateway-auth resolve. Verify the renamed mcp_external_client_url field appears correctly in the API reference.

Screenshots/Recordings

New page includes screenshots of the OAuth consent UI (ui-oauth-consent.png), the MCP server auth mode config panel (ui-mcp-server-auth-mode.png), and the OAuth grants table (ui-oauth-grants.png).

Breaking changes

• Yes
• No

The mcp_external_base_url config field is renamed to mcp_external_client_url. Any existing configuration using the old field name will need to be updated.

Related issues

Related to the Claude Code DCR probe error reported at anthropics/claude-code#46640.

Security considerations

The new OAuth 2.1 authorization server surface (when mcp_server_auth_mode is both or oauth) issues short-lived JWTs signed with an auto-generated RSA key. Refresh tokens rotate on each use. Grants can be revoked from the UI. In oauth mode, header-based credentials (virtual keys, API keys) are rejected on /mcp, tightening the inbound auth surface. The access_token_ttl default of 600 seconds bounds the window between a revoke and full enforcement.

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

[Pratham-Mishra04]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• tests: add MCP auth e2e collection covering discovery, credential matrix, OAuth issuance, refresh rotation, revocation window, and runtime mode flip #4525
• tests: add MCP auth mode e2e collection and Newman runner for headers/both/oauth #4524
• tests: add OAuth2 issuance, JWT verification, consent, discovery, sessions, and MCP auth unit tests #4523
• feat: add mcp_server_auth_mode and OAuth 2.1 gateway auth docs with gateway-auth page #4522 👈 (View in Graphite)
• ui: add OAuth Grants page and identity exact-match filter for MCP sessions #4511
• ui: add OAuth2 consent page and MCP server auth mode settings #4510
• feat: add OAuth2 session listing, revocation, family-revocation, VK liveness check, and sweep worker #4509
• feat: add JWT Bearer authentication path for /mcp with session validation and context injection #4508
• feat: add OAuth2ConsentHandler with VK, session, and user identity resolution modes #4507
• feat: add OAuth2 issuance endpoints (DCR, authorize, token) with PKCE and refresh token rotation #4506
• feat: add OAuth2 AS discovery endpoints, signing key management, and MCPServerAuthMode config #4505
• 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.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 0bcf7cc1-5974-4aa8-8d23-22200f0e0d1b

📥 Commits

Reviewing files that changed from the base of the PR and between 47877f6 and a69e4b4.

⛔ Files ignored due to path filters (3)

• docs/media/ui-mcp-server-auth-mode.png is excluded by !**/*.png
• docs/media/ui-oauth-consent.png is excluded by !**/*.png
• docs/media/ui-oauth-grants.png is excluded by !**/*.png

📒 Files selected for processing (6)

• docs/cli-agents/claude-code.mdx
• docs/docs.json
• docs/mcp/gateway-auth.mdx
• docs/mcp/gateway.mdx
• docs/openapi/openapi.json
• docs/openapi/schemas/management/config.yaml

✅ Files skipped from review due to trivial changes (4)

• docs/cli-agents/claude-code.mdx
• docs/docs.json
• docs/mcp/gateway-auth.mdx
• docs/mcp/gateway.mdx

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

• docs/openapi/openapi.json
• docs/openapi/schemas/management/config.yaml

---

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Added guidance for MCP Gateway authentication, including OAuth, header-based auth, and per-user credentials.
  • Documented new authentication configuration options for MCP server and OAuth client settings.

• Documentation

  • Added a new page covering external MCP client authentication and related setup.
  • Updated existing MCP docs to clarify re-authentication behavior and troubleshooting steps.

• Bug Fixes

  • Clarified that a Claude Code SDK auth parse error is cosmetic in default header-based mode, and that tools should be refreshed with Reconnect.

Walkthrough

Adds a new docs/mcp/gateway-auth.mdx page documenting MCP Gateway OAuth authentication modes. Renames mcp_external_base_url to mcp_external_client_url and adds mcp_server_auth_mode and oauth2_server_config in schema docs. Updates gateway.mdx, claude-code.mdx, and navigation to match the new auth flow.

Changes

MCP Gateway OAuth Authentication Documentation and Schema

Layer / File(s)	Summary
ClientConfig schema: renamed URL and new OAuth fields docs/openapi/schemas/management/config.yaml, docs/openapi/openapi.json	Renames mcp_external_base_url to mcp_external_client_url with updated redirect_uri description; adds mcp_server_auth_mode enum (headers/both/oauth, default headers) and oauth2_server_config object (issuer_url, auth_code_ttl, access_token_ttl) to ClientConfig. Rename is propagated into both repeated sections of openapi.json.
New Gateway Authentication docs page docs/mcp/gateway-auth.mdx	Introduces the Gateway Authentication reference page covering auth modes, OAuth 2.1 connect flow, consent-time identity modes, configuration via UI/API/config.json, grant management, token lifetimes, discovery endpoint behavior, and troubleshooting.
Cross-references in gateway.mdx and claude-code.mdx docs/mcp/gateway.mdx, docs/cli-agents/claude-code.mdx	Adds a note in gateway.mdx pointing to the OAuth browser flow; rewrites Per-User Auth to reflect auth-mode-dependent identity; corrects the DCR endpoint reference from /register to /oauth2/register. Updates claude-code.mdx FAQ to clarify the 405 parse error is cosmetic in headers mode and replaces Re-authenticate with Reconnect guidance.
Navigation update for new gateway-auth page docs/docs.json	Adds the new mcp/gateway-auth page path to the MCP Gateway navigation group.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 Hop hop, the docs grow wide,
New auth modes now documented with pride,
/oauth2/register — the right trail to follow,
mcp_external_client_url fills the hollow,
Reconnect, not Re-authenticate, says the guide,
The gateway bunny waves from the OAuth slide! 🌟

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: new MCP gateway auth docs and the mcp_server_auth_mode feature.
Description check	✅ Passed	The description follows the template closely and covers summary, changes, testing, breaking changes, security, and checklist sections.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 06-18-docs_adds_docs_for_mcp_oauth_server

---

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

[greptile-apps]

Confidence Score: 5/5

Documentation-only change; no Go or UI runtime code is modified in this diff.

The new gateway-auth page, schema additions, and cross-reference updates are accurate and internally consistent. The only gaps are that schema-reference.mdx omits the two new client config fields, the Helm chart doesn't expose them as first-class values, and config.schema.json lacks the formal default keyword for mcp_server_auth_mode that the generated OpenAPI specs both carry — none of which affect runtime behavior.

transports/config.schema.json (missing default for mcp_server_auth_mode); docs/deployment-guides/config-json/schema-reference.mdx (new fields absent from the table); helm-charts/bifrost/values.schema.json (new fields not exposed as Helm values).

Important Files Changed

Filename	Overview
docs/mcp/gateway-auth.mdx	New page documenting the three auth modes, OAuth 2.1 connect flow with sequence diagram, identity modes, configuration, grant management, and troubleshooting — content is accurate and consistent with the OpenAPI schema.
docs/openapi/schemas/management/config.yaml	Renames mcp_external_base_url to mcp_external_client_url and adds mcp_server_auth_mode and oauth2_server_config; consistent with openapi.json and config.schema.json changes.
docs/openapi/openapi.json	Renames field and adds two new config objects in both PUT schema occurrences; consistent with config.yaml changes.
transports/config.schema.json	Adds new fields correctly, but mcp_server_auth_mode is missing the default: "headers" keyword that openapi.json and config.yaml both include, creating a minor divergence in the source-of-truth schema.
docs/mcp/gateway.mdx	Adds cross-references to the new gateway-auth page and clarifies the DCR probe behavior per auth mode; accurate and consistent.
docs/cli-agents/claude-code.mdx	Scopes the DCR probe workaround note to headers mode and clarifies both/oauth mode behavior; accurate.
docs/docs.json	Adds mcp/gateway-auth to the MCP Gateway navigation group in the correct position.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant C as MCP Client
    participant U as User (Browser)
    participant B as Bifrost OAuth AS

    C->>B: GET /mcp (no token)
    B-->>C: 401 + WWW-Authenticate (resource metadata URL)
    C->>B: GET /.well-known/oauth-protected-resource
    B-->>C: Resource metadata (AS URL)
    C->>B: GET /.well-known/oauth-authorization-server
    B-->>C: AS metadata (endpoints, JWKS URI)
    C->>B: POST /oauth2/register (RFC 7591 DCR)
    B-->>C: client_id
    C->>U: "Open /oauth2/authorize?code_challenge=S256... in browser"
    U->>B: Consent page (choose virtual key / session / user)
    B-->>U: "302 to client redirect_uri?code=..."
    U-->>C: Authorization code via redirect
    C->>B: POST /oauth2/token (code + code_verifier)
    B-->>C: "access_token (JWT, TTL=600s) + refresh_token (rotating)"
    C->>B: GET/POST /mcp (Authorization: Bearer JWT)
    B-->>C: Tools available

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant C as MCP Client
    participant U as User (Browser)
    participant B as Bifrost OAuth AS

    C->>B: GET /mcp (no token)
    B-->>C: 401 + WWW-Authenticate (resource metadata URL)
    C->>B: GET /.well-known/oauth-protected-resource
    B-->>C: Resource metadata (AS URL)
    C->>B: GET /.well-known/oauth-authorization-server
    B-->>C: AS metadata (endpoints, JWKS URI)
    C->>B: POST /oauth2/register (RFC 7591 DCR)
    B-->>C: client_id
    C->>U: "Open /oauth2/authorize?code_challenge=S256... in browser"
    U->>B: Consent page (choose virtual key / session / user)
    B-->>U: "302 to client redirect_uri?code=..."
    U-->>C: Authorization code via redirect
    C->>B: POST /oauth2/token (code + code_verifier)
    B-->>C: "access_token (JWT, TTL=600s) + refresh_token (rotating)"
    C->>B: GET/POST /mcp (Authorization: Bearer JWT)
    B-->>C: Tools available

Loading

_{Reviews (11): Last reviewed commit: "docs: adds docs for mcp oauth server" | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/mcp/gateway.mdx (1)

314-352: ⚠️ Potential issue | 🔴 Critical

Complete documentation of mcp_external_base_url split and missing mcp_external_server_url.

The field refactor is more significant than a simple rename: mcp_external_base_url was split into two distinct fields (mcp_external_server_url and mcp_external_client_url) in the database migrations (framework/configstore/migrations.go). The current documentation only covers mcp_external_client_url and omits mcp_external_server_url entirely. Additionally, this breaking change is not documented in the v1.5.0 migration guide (docs/migration-guides/v1.5.0.mdx), which covers many other breaking changes. The breaking change warning in gateway.mdx correctly applies to mcp_external_client_url, but the documentation should clarify the split, define the purpose of both resulting fields, and ensure the migration guide covers this change.

🤖 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 `@docs/mcp/gateway.mdx` around lines 314 - 352, The current documentation in
gateway.mdx only describes mcp_external_client_url and completely omits
mcp_external_server_url, even though mcp_external_base_url was split into these
two distinct fields. Add documentation for mcp_external_server_url in the
"Public URL configuration when behind a proxy" section that explains its
distinct purpose compared to mcp_external_client_url, clarify that this was a
split from the original mcp_external_base_url field, and specify when each field
should be used. Additionally, add a breaking change entry to
docs/migration-guides/v1.5.0.mdx documenting this split and providing migration
guidance for users upgrading from previous versions.

🤖 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 `@docs/docs.json`:
- Around line 531-533: Fix the indentation of the
"deployment-guides/config-json/source-of-truth" entry in the docs.json file by
adjusting its leading whitespace to align with the adjacent array entries
"deployment-guides/config-json" and
"deployment-guides/config-json/schema-reference" to ensure consistent
indentation throughout the array.

---

Outside diff comments:
In `@docs/mcp/gateway.mdx`:
- Around line 314-352: The current documentation in gateway.mdx only describes
mcp_external_client_url and completely omits mcp_external_server_url, even
though mcp_external_base_url was split into these two distinct fields. Add
documentation for mcp_external_server_url in the "Public URL configuration when
behind a proxy" section that explains its distinct purpose compared to
mcp_external_client_url, clarify that this was a split from the original
mcp_external_base_url field, and specify when each field should be used.
Additionally, add a breaking change entry to docs/migration-guides/v1.5.0.mdx
documenting this split and providing migration guidance for users upgrading from
previous versions.

🪄 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: ea0ba857-deb5-467d-ac5f-00861ae1def8

📥 Commits

Reviewing files that changed from the base of the PR and between 8bff02e and 91623fa.

⛔ Files ignored due to path filters (3)

• docs/media/ui-mcp-server-auth-mode.png is excluded by !**/*.png
• docs/media/ui-oauth-consent.png is excluded by !**/*.png
• docs/media/ui-oauth-grants.png is excluded by !**/*.png

📒 Files selected for processing (6)

• docs/cli-agents/claude-code.mdx
• docs/docs.json
• docs/mcp/gateway-auth.mdx
• docs/mcp/gateway.mdx
• docs/openapi/openapi.json
• docs/openapi/schemas/management/config.yaml