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]

• tests: add MCP auth e2e collection covering discovery, credential matrix, OAuth issuance, refresh rotation, revocation window, and runtime mode flip #4525 : 2 dependent PRs (#4744 , #4750 )
• 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
• refactor: rename MCP handler files to remove underscores and drop redundant prefixes #4747
• 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]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 27 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 35fc7425-21e9-4432-99c2-5b71e9bf7eb4

📥 Commits

Reviewing files that changed from the base of the PR and between c1d6601 and 8872519.

⛔ 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

📝 Walkthrough

Walkthrough

Adds a new MCP Gateway authentication page, updates MCP auth-related schema fields, and revises related gateway, Claude Code, and navigation documentation.

Changes

MCP Gateway OAuth Authentication Documentation and Schema

Layer / File(s)	Summary
ClientConfig schema and OpenAPI fields docs/openapi/schemas/management/config.yaml, docs/openapi/openapi.json	Renames mcp_external_base_url to mcp_external_client_url, updates the description, and adds mcp_server_auth_mode plus oauth2_server_config to the management schema and repeated OpenAPI schema sections.
Gateway authentication page docs/mcp/gateway-auth.mdx	Adds the new Gateway Authentication page covering auth modes, OAuth connect flow, consent identity options, configuration, token lifecycle, discovery behavior, and troubleshooting.
Gateway docs, Claude Code FAQ, and navigation docs/mcp/gateway.mdx, docs/cli-agents/claude-code.mdx, docs/docs.json	Updates gateway docs to reference the new auth flow and /oauth2/register, revises the Claude Code FAQ guidance for the 405 response, and adds the new page to navigation.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested reviewers

• akshaydeo
• danpiths

Poem

🐇 Hop, hop — the docs got bright,
OAuth paths now read just right.
New gateway page, new names in sight,
Reconnect leads the bunny light.

🚥 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 config and documentation.
Description check	✅ Passed	The description follows the template and covers the required sections, with only minor gaps like no concrete test commands.
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.

✨ 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; the underlying implementation is already shipped and the new schema fields match transports/config.schema.json exactly.

All schema additions align with the implementation. The gateway-auth.mdx content is accurate against the Go source — JWT gating, grant persistence, RSA key lifecycle, and enforce_auth_on_inference semantics are all correctly described. The only inconsistency is a stale /register path in claude-code.mdx where gateway.mdx already uses the correct /oauth2/register; this has no runtime impact.

docs/cli-agents/claude-code.mdx — DCR probe path /register should be /oauth2/register to match gateway.mdx and the implementation.

Important Files Changed

Filename	Overview
docs/mcp/gateway-auth.mdx	New page covering all three auth modes, OAuth 2.1 consent flow, identity modes, configuration, grant management, and troubleshooting — accurate against implementation
docs/cli-agents/claude-code.mdx	Troubleshooting note scoped to headers mode; DCR probe path still reads /register while gateway.mdx uses the correct /oauth2/register
docs/mcp/gateway.mdx	Per-user auth section updated to reference gateway auth mode; DCR probe note updated to /oauth2/register (matches implementation)
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 — aligned with transports/config.schema.json
docs/openapi/openapi.json	Field rename and new fields consistent with config.yaml source
docs/docs.json	Adds mcp/gateway-auth to the MCP Gateway nav 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

    C->>B: GET /mcp (no token)
    B-->>C: 401 + WWW-Authenticate pointing to /.well-known/oauth-protected-resource/mcp
    C->>B: GET /.well-known/oauth-protected-resource/mcp
    B-->>C: Protected resource metadata (auth server URL)
    C->>B: GET /.well-known/oauth-authorization-server
    B-->>C: AS metadata (authorize/token/register endpoints)
    C->>B: POST /oauth2/register (DCR)
    B-->>C: client_id
    C->>U: Open /oauth2/authorize (PKCE)
    U->>B: Consent page - choose identity (VK / session / user)
    B-->>U: 302 redirect with authorization code
    U-->>C: Code delivered to redirect_uri
    C->>B: POST /oauth2/token (code + code_verifier)
    B-->>C: access_token (JWT, RS256) + refresh_token
    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

    C->>B: GET /mcp (no token)
    B-->>C: 401 + WWW-Authenticate pointing to /.well-known/oauth-protected-resource/mcp
    C->>B: GET /.well-known/oauth-protected-resource/mcp
    B-->>C: Protected resource metadata (auth server URL)
    C->>B: GET /.well-known/oauth-authorization-server
    B-->>C: AS metadata (authorize/token/register endpoints)
    C->>B: POST /oauth2/register (DCR)
    B-->>C: client_id
    C->>U: Open /oauth2/authorize (PKCE)
    U->>B: Consent page - choose identity (VK / session / user)
    B-->>U: 302 redirect with authorization code
    U-->>C: Code delivered to redirect_uri
    C->>B: POST /oauth2/token (code + code_verifier)
    B-->>C: access_token (JWT, RS256) + refresh_token
    C->>B: GET/POST /mcp (Authorization: Bearer JWT)
    B-->>C: Tools available

Loading

_{Reviews (25): 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

[Pratham-Mishra04]

Merge activity

• Jun 30, 1:53 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Jun 30, 2:17 PM UTC: Graphite rebased this pull request as part of a merge.
• Jun 30, 2:18 PM UTC: @Pratham-Mishra04 merged this pull request with Graphite.

The base branch was changed.