docs: add mcp sessions page and refactor per-user oauth to lazy-auth model#3706
Merged
Pratham-Mishra04 merged 2 commits intoMay 27, 2026
Merged
Conversation
18 tasks
Contributor
|
Warning Review limit reached
More reviews will be available in 11 minutes and 57 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: ⛔ Files ignored due to path filters (13)
📒 Files selected for processing (18)
📝 WalkthroughWalkthroughCentralizes MCP authentication docs into a new auth hub (overview + per-auth pages), adds MCP Sessions, reorganizes navigation/redirects, updates gateway and connection docs, and fixes legacy ChangesMCP Authentication Documentation Restructure
Navigation, Integration, and Cross-Reference Updates
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
This was referenced May 23, 2026
|
|
Collaborator
Author
This was referenced May 23, 2026
Closed
Pratham-Mishra04
force-pushed
the
05-23-fix_mcp_auth_session_reconciliation_fixes
branch
from
79fe495 to
fb2ba5b
Compare
Pratham-Mishra04
force-pushed
the
05-21-docs_adds_per_user_mcp_connection_docs
branch
from
2c16bfc to
9e853a7
Compare
Contributor
Security Policy Alert: Secret Policy ViolationThis workflow run has been blocked by StepSecurity's secrets policy because it accesses secrets and the workflow file differs from the default branch. To approve this workflow, please add the Note: The label must be added by someone other than the PR author (Pratham-Mishra04) or automation bots to ensure proper security review. After the label is added, you can re-run the blocked workflow to proceed. This workflow will be automatically approved once merged into the default branch. For more information, see StepSecurity's Secret Exfiltration Policy documentation. |
Contributor
Confidence Score: 4/5Safe to merge for the structural and navigation changes; the session-ID guidance gap should be addressed before the docs ship publicly. The changes are docs-only and the restructuring is internally consistent. The one concern that warrants attention before publication is that the introduction of docs/mcp/auth/overview.mdx — session ID security guidance; docs/mcp/auth/per-user-oauth.mdx and docs/mcp/auth/per-user-headers.mdx — orphaned-credential clarification in the "How it works" steps.
|
| Filename | Overview |
|---|---|
| docs/mcp/auth/overview.mdx | New auth overview page introducing identity modes and lazy-auth model; session ID security guidance is missing at the point where the header is introduced. |
| docs/mcp/auth/per-user-oauth.mdx | New per-user OAuth page correctly documents the lazy-auth model; "How it works" step 3 groups orphaned with needs_reauth without noting that re-auth won't fix orphaned rows. |
| docs/mcp/auth/per-user-headers.mdx | New per-user headers page; same orphaned-as-auth-fixable issue as per-user-oauth.mdx in the "How it works" section. Client name hyphen constraint is now correctly documented. |
| docs/mcp/sessions.mdx | New MCP Sessions page; revoke race-condition fix is documented only for OAuth pending flows, leaving the same race for header submission flows unaddressed. |
| docs/mcp/gateway.mdx | New consolidated MCP Gateway page replacing gateway-url.mdx; covers VK auth, per-user auth on the gateway, tool auto-execution note, and the Claude Code DCR probe caveat. No issues found. |
| docs/mcp/auth/oauth.mdx | New server-level OAuth page; covers PKCE, DCR, discovery, token management, and provider snippets. DCR redirect_uri locking warning is present and consistent with other pages. |
| docs/mcp/auth/headers.mdx | New static headers auth page; correctly scopes this as server-level auth and points to per-user-headers for the per-caller variant. |
| docs/mcp/auth/none.mdx | New "no auth" page; immutability constraint is now phrased as a constraint (delete and re-create), removing the confusing "can be edited later" wording. |
| docs/docs.json | Sidebar restructured to add Authentication sub-group and Sessions page; redirects added for all removed/renamed routes (mcp/oauth, mcp/per-user-oauth, mcp/gateway-url). |
| docs/mcp/connecting-to-servers.mdx | Simplified connection-type table; detailed per-auth-type examples removed and replaced with a pointer to the new auth sub-section. STDIO example now explicitly shows auth_type: none. |
Reviews (15): Last reviewed commit: "docs: mcp docs update" | Re-trigger Greptile
Pratham-Mishra04
force-pushed
the
05-21-docs_adds_per_user_mcp_connection_docs
branch
from
9e853a7 to
85ef4ca
Compare
Pratham-Mishra04
force-pushed
the
05-23-fix_mcp_auth_session_reconciliation_fixes
branch
from
fb2ba5b to
5919a07
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
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 (2)
docs/mcp/auth/overview.mdx (1)
8-143:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd required Mintlify tab set to this page.
This page currently has no Web UI / API / config.json tabs, which violates the docs MDX convention used in this stack.
As per coding guidelines: “
docs/**/*.mdx: Mintlify MDX documentation must have Web UI / API / config.json tabs; validate config.json examples against transports/config.schema.json”.🤖 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/auth/overview.mdx` around lines 8 - 143, The page docs/mcp/auth/overview.mdx is missing the required Mintlify tab set (Web UI / API / config.json); add the Mintlify tab block at the top of the doc (around the "## Overview" section) with three tabs named "Web UI", "API", and "config.json", move or duplicate appropriate snippets into each tab (UI prose into Web UI, endpoint details into API, and the JSON config example into config.json), and ensure any config.json example validates against transports/config.schema.json before committing.docs/mcp/sessions.mdx (1)
8-195:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd required Mintlify tab structure to this page.
The page lacks the expected Web UI / API / config.json tabs required for MDX docs consistency in this repo.
As per coding guidelines: “
docs/**/*.mdx: Mintlify MDX documentation must have Web UI / API / config.json tabs; validate config.json examples against transports/config.schema.json”.🤖 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/sessions.mdx` around lines 8 - 195, Add the Mintlify tab wrapper with three tabs titled "Web UI", "API", and "config.json" around the existing MDX content (the block currently starting at the "## Overview" heading and containing components like <Info> and <Frame>), placing the current prose and images into the "Web UI" tab, any API examples or links into the "API" tab, and a JSON example into the "config.json" tab; ensure the config.json example in the "config.json" tab is a valid example that conforms to transports/config.schema.json before committing.
🧹 Nitpick comments (1)
docs/mcp/gateway.mdx (1)
363-368: Docs config.json path is correct (client.mcp_disable_auto_tool_inject), but it’s the deprecated setting—consider documenting the current one.
transports/config.schema.jsondefinesclient.mcp_disable_auto_tool_inject(deprecated) and yourdocs/mcp/gateway.mdxconfig.jsonexample matches it (client.mcp_disable_auto_tool_inject: true).- The schema also defines the non-deprecated equivalent at
mcp.tool_manager_config.disable_auto_tool_inject; the docs should either switch to that path or explicitly mention that the shownclient.mcp_disable_auto_tool_injectis deprecated and points to the newer field. [optional improvement at docs/mcp/gateway.mdx:363-368]🤖 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 363 - 368, The docs example uses the deprecated key client.mcp_disable_auto_tool_inject; update docs/mcp/gateway.mdx to either replace that example with the current key mcp.tool_manager_config.disable_auto_tool_inject (showing the new full JSON path) or explicitly annotate the existing snippet to state that client.mcp_disable_auto_tool_inject is deprecated and point readers to mcp.tool_manager_config.disable_auto_tool_inject as the preferred setting; mention both keys so readers can map the old -> new.
🤖 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/mcp/auth/per-user-oauth.mdx`:
- Around line 35-57: The docs page uses a Tabs/Tab structure but only includes
the "Web UI" Tab; add two additional Tab entries titled "API" and "config.json"
alongside the existing <Tab title="Web UI"> block, providing brief placeholder
content (e.g., "Not applicable" or "Unsupported" if no API) for the API tab and
a validated example config JSON for the config.json tab; ensure the config.json
example conforms to transports/config.schema.json and reference the Per-User
OAuth fields (client_id, client_secret, authorize_url, token_url, scopes) so the
config keys match the schema.
---
Outside diff comments:
In `@docs/mcp/auth/overview.mdx`:
- Around line 8-143: The page docs/mcp/auth/overview.mdx is missing the required
Mintlify tab set (Web UI / API / config.json); add the Mintlify tab block at the
top of the doc (around the "## Overview" section) with three tabs named "Web
UI", "API", and "config.json", move or duplicate appropriate snippets into each
tab (UI prose into Web UI, endpoint details into API, and the JSON config
example into config.json), and ensure any config.json example validates against
transports/config.schema.json before committing.
In `@docs/mcp/sessions.mdx`:
- Around line 8-195: Add the Mintlify tab wrapper with three tabs titled "Web
UI", "API", and "config.json" around the existing MDX content (the block
currently starting at the "## Overview" heading and containing components like
<Info> and <Frame>), placing the current prose and images into the "Web UI" tab,
any API examples or links into the "API" tab, and a JSON example into the
"config.json" tab; ensure the config.json example in the "config.json" tab is a
valid example that conforms to transports/config.schema.json before committing.
---
Nitpick comments:
In `@docs/mcp/gateway.mdx`:
- Around line 363-368: The docs example uses the deprecated key
client.mcp_disable_auto_tool_inject; update docs/mcp/gateway.mdx to either
replace that example with the current key
mcp.tool_manager_config.disable_auto_tool_inject (showing the new full JSON
path) or explicitly annotate the existing snippet to state that
client.mcp_disable_auto_tool_inject is deprecated and point readers to
mcp.tool_manager_config.disable_auto_tool_inject as the preferred setting;
mention both keys so readers can map the old -> new.
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: a005df3b-ec26-4910-9346-578dc8adabe2
📒 Files selected for processing (18)
docs/cli-agents/claude-desktop.mdxdocs/cli-agents/overview.mdxdocs/cli-agents/roo-code.mdxdocs/docs.jsondocs/mcp/auth/headers.mdxdocs/mcp/auth/none.mdxdocs/mcp/auth/oauth.mdxdocs/mcp/auth/overview.mdxdocs/mcp/auth/per-user-headers.mdxdocs/mcp/auth/per-user-oauth.mdxdocs/mcp/code-mode.mdxdocs/mcp/connecting-to-servers.mdxdocs/mcp/gateway.mdxdocs/mcp/oauth.mdxdocs/mcp/overview.mdxdocs/mcp/per-user-oauth.mdxdocs/mcp/sessions.mdxdocs/overview.mdx
💤 Files with no reviewable changes (2)
- docs/mcp/oauth.mdx
- docs/mcp/per-user-oauth.mdx
Pratham-Mishra04
force-pushed
the
05-23-fix_mcp_auth_session_reconciliation_fixes
branch
from
5919a07 to
24adf78
Compare
Pratham-Mishra04
force-pushed
the
05-21-docs_adds_per_user_mcp_connection_docs
branch
from
85ef4ca to
1a35406
Compare
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/mcp/auth/per-user-oauth.mdx (1)
132-134: 💤 Low valueMinor: Vary sentence openings for better flow.
Three consecutive sentences begin with "Authenticate via". Consider rephrasing one or two for variety.
✍️ Suggested rewording
-- Authenticate via the **LLM Gateway** with `vk_xyz` → that token is immediately usable on the **MCP Gateway** as long as the inbound request also carries `vk_xyz`. -- Authenticate via the **MCP Gateway** with `x-bf-mcp-session-id=abc` → the **LLM Gateway** can reuse it by sending the same `x-bf-mcp-session-id` header. -- Authenticate via enterprise SSO as user `u_123` on either gateway → the other gateway also reuses the token automatically (no header to set). +- Authenticate via the **LLM Gateway** with `vk_xyz` → that token is immediately usable on the **MCP Gateway** as long as the inbound request also carries `vk_xyz`. +- Use the **MCP Gateway** with `x-bf-mcp-session-id=abc` → the **LLM Gateway** can reuse it by sending the same `x-bf-mcp-session-id` header. +- Sign in via enterprise SSO as user `u_123` on either gateway → the other gateway also reuses the token automatically (no header to set).🤖 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/auth/per-user-oauth.mdx` around lines 132 - 134, Three consecutive lines begin with "Authenticate via" which makes the paragraph repetitive; update one or two sentences to vary their openings while keeping the same meaning and tokens (`vk_xyz`, `x-bf-mcp-session-id=abc`, `u_123`, LLM Gateway, MCP Gateway). For example, keep the first sentence about the LLM Gateway as-is, then start the second with "Use the MCP Gateway to authenticate with `x-bf-mcp-session-id=abc`…" and begin the third with "Enterprise SSO as user `u_123` on either gateway…" so each sentence has a distinct opening but still mentions the exact headers/tokens and the reuse behavior.
🤖 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 `@docs/mcp/auth/per-user-oauth.mdx`:
- Around line 132-134: Three consecutive lines begin with "Authenticate via"
which makes the paragraph repetitive; update one or two sentences to vary their
openings while keeping the same meaning and tokens (`vk_xyz`,
`x-bf-mcp-session-id=abc`, `u_123`, LLM Gateway, MCP Gateway). For example, keep
the first sentence about the LLM Gateway as-is, then start the second with "Use
the MCP Gateway to authenticate with `x-bf-mcp-session-id=abc`…" and begin the
third with "Enterprise SSO as user `u_123` on either gateway…" so each sentence
has a distinct opening but still mentions the exact headers/tokens and the reuse
behavior.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 4d523234-f3bb-456c-a0df-55c014830cb5
📒 Files selected for processing (18)
docs/cli-agents/claude-desktop.mdxdocs/cli-agents/overview.mdxdocs/cli-agents/roo-code.mdxdocs/docs.jsondocs/mcp/auth/headers.mdxdocs/mcp/auth/none.mdxdocs/mcp/auth/oauth.mdxdocs/mcp/auth/overview.mdxdocs/mcp/auth/per-user-headers.mdxdocs/mcp/auth/per-user-oauth.mdxdocs/mcp/code-mode.mdxdocs/mcp/connecting-to-servers.mdxdocs/mcp/gateway.mdxdocs/mcp/oauth.mdxdocs/mcp/overview.mdxdocs/mcp/per-user-oauth.mdxdocs/mcp/sessions.mdxdocs/overview.mdx
💤 Files with no reviewable changes (2)
- docs/mcp/per-user-oauth.mdx
- docs/mcp/oauth.mdx
✅ Files skipped from review due to trivial changes (9)
- docs/cli-agents/roo-code.mdx
- docs/cli-agents/overview.mdx
- docs/mcp/connecting-to-servers.mdx
- docs/mcp/overview.mdx
- docs/mcp/auth/headers.mdx
- docs/mcp/auth/overview.mdx
- docs/mcp/auth/oauth.mdx
- docs/mcp/auth/none.mdx
- docs/mcp/sessions.mdx
Pratham-Mishra04
force-pushed
the
05-23-fix_mcp_auth_session_reconciliation_fixes
branch
from
24adf78 to
dbf3e80
Compare
Pratham-Mishra04
force-pushed
the
05-21-docs_adds_per_user_mcp_connection_docs
branch
from
1a35406 to
1646fc5
Compare
18 tasks
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (1)
docs/mcp/auth/per-user-oauth.mdx (1)
35-56:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd API and config.json tabs to match documentation standards.
The Tabs section currently only includes the Web UI tab. Per coding guidelines, Mintlify MDX documentation must include Web UI / API / config.json tabs. While line 33 mentions this feature is "Web UI only," the missing tabs should still be present with explicit "not supported" messages, following the pattern in
per-user-headers.mdx(lines 122-126).📝 Suggested tab structure
Add API and config.json tabs after the Web UI tab:
</Tab> <Tab title="API"> Per-user OAuth setup is **not supported** via the API. The setup flow requires an interactive OAuth popup to run the admin test flow and discover tools. Use the Web UI to create per-user OAuth MCP clients. Once created, you can query the resulting configuration: ```bash curl -X GET http://localhost:8080/api/mcp/client/{id}File-based config is not supported for
per_user_oauth. Bifrost needs to run a test OAuth flow during setup to discover the upstream tool list, which can only happen via an interactive admin step (Web UI).If you want a declarative-ish setup, create the MCP client once via the Web UI, then reference the resulting
```mcp_client_idfrom other parts of your system. The MCP client itself stays in Bifrost's database.As per coding guidelines: "
docs/**/*.mdx: Mintlify MDX documentation must have Web UI / API / config.json tabs".🤖 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/auth/per-user-oauth.mdx` around lines 35 - 56, The Tabs block only has the "Web UI" Tab; add two additional Tab entries titled "API" and "config.json" after the existing Web UI Tab to conform to the Mintlify MDX requirement (Web UI / API / config.json). In the "API" Tab, add a short "Per-user OAuth setup is not supported via the API" message, explain that the admin interactive OAuth popup is required and include a single-line example GET command to fetch the created MCP client (referencing the resulting mcp client id). In the "config.json" Tab, state that file-based config is not supported for per_user_oauth because the test OAuth flow must run interactively and suggest the workflow: create via Web UI then reference the mcp_client_id elsewhere. Use the same Tab/</Tab> structure (Tabs, Tab title="API", Tab title="config.json") as in the existing snippet and mirror the wording/pattern used in per-user-headers.mdx.
🤖 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.
Duplicate comments:
In `@docs/mcp/auth/per-user-oauth.mdx`:
- Around line 35-56: The Tabs block only has the "Web UI" Tab; add two
additional Tab entries titled "API" and "config.json" after the existing Web UI
Tab to conform to the Mintlify MDX requirement (Web UI / API / config.json). In
the "API" Tab, add a short "Per-user OAuth setup is not supported via the API"
message, explain that the admin interactive OAuth popup is required and include
a single-line example GET command to fetch the created MCP client (referencing
the resulting mcp client id). In the "config.json" Tab, state that file-based
config is not supported for per_user_oauth because the test OAuth flow must run
interactively and suggest the workflow: create via Web UI then reference the
mcp_client_id elsewhere. Use the same Tab/</Tab> structure (Tabs, Tab
title="API", Tab title="config.json") as in the existing snippet and mirror the
wording/pattern used in per-user-headers.mdx.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 8f58f080-209f-49f3-955c-ed49ddd82ef0
📒 Files selected for processing (18)
docs/cli-agents/claude-desktop.mdxdocs/cli-agents/overview.mdxdocs/cli-agents/roo-code.mdxdocs/docs.jsondocs/mcp/auth/headers.mdxdocs/mcp/auth/none.mdxdocs/mcp/auth/oauth.mdxdocs/mcp/auth/overview.mdxdocs/mcp/auth/per-user-headers.mdxdocs/mcp/auth/per-user-oauth.mdxdocs/mcp/code-mode.mdxdocs/mcp/connecting-to-servers.mdxdocs/mcp/gateway.mdxdocs/mcp/oauth.mdxdocs/mcp/overview.mdxdocs/mcp/per-user-oauth.mdxdocs/mcp/sessions.mdxdocs/overview.mdx
💤 Files with no reviewable changes (2)
- docs/mcp/per-user-oauth.mdx
- docs/mcp/oauth.mdx
✅ Files skipped from review due to trivial changes (8)
- docs/cli-agents/overview.mdx
- docs/cli-agents/roo-code.mdx
- docs/cli-agents/claude-desktop.mdx
- docs/mcp/sessions.mdx
- docs/mcp/gateway.mdx
- docs/mcp/connecting-to-servers.mdx
- docs/mcp/auth/overview.mdx
- docs/mcp/auth/oauth.mdx
Pratham-Mishra04
force-pushed
the
05-21-docs_adds_per_user_mcp_connection_docs
branch
from
1646fc5 to
e6d99be
Compare
Pratham-Mishra04
force-pushed
the
05-23-fix_mcp_auth_session_reconciliation_fixes
branch
from
dbf3e80 to
44bcebd
Compare
Pratham-Mishra04
force-pushed
the
05-23-fix_mcp_auth_session_reconciliation_fixes
branch
from
3e4f2f5 to
e435e91
Compare
Pratham-Mishra04
force-pushed
the
05-21-docs_adds_per_user_mcp_connection_docs
branch
from
849fbd6 to
35b1028
Compare
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
Pratham-Mishra04
force-pushed
the
05-21-docs_adds_per_user_mcp_connection_docs
branch
from
35b1028 to
515b609
Compare
Pratham-Mishra04
force-pushed
the
05-23-fix_mcp_auth_session_reconciliation_fixes
branch
from
e435e91 to
6a51858
Compare
Pratham-Mishra04
force-pushed
the
05-21-docs_adds_per_user_mcp_connection_docs
branch
from
515b609 to
690fa9a
Compare
18 tasks
Contributor
There was a problem hiding this comment.
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 `@docs/mcp/auth/per-user-headers.mdx`:
- Line 178: Replace the phrase "inline-401" with the agreed terminology
"mcp_auth_required" (or describe as "inline auth URL" / "`mcp_auth_required`
URL") in the sentence that currently reads "When an end-user hits the inline-401
URL, they land on `/workspace/mcp-sessions/auth?flow=<id>&kind=headers`:" and
the corresponding occurrence at the other location; ensure both instances use
the exact token `mcp_auth_required` (or the parenthetical "inline auth URL") so
the doc matches the lazy-auth model used elsewhere.
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 84cf7c72-b795-4582-8f20-cbae21a8935e
⛔ Files ignored due to path filters (13)
docs/media/ui-config-mcp-disable-auto-tool-inject.pngis excluded by!**/*.pngdocs/media/ui-mcp-auth-headers-form.pngis excluded by!**/*.pngdocs/media/ui-mcp-auth-none-form.pngis excluded by!**/*.pngdocs/media/ui-mcp-auth-oauth-popup.pngis excluded by!**/*.pngdocs/media/ui-mcp-auth-per-user-headers-verify-dialog.pngis excluded by!**/*.pngdocs/media/ui-mcp-per-user-auth-flow-lazy.svgis excluded by!**/*.svgdocs/media/ui-mcp-per-user-headers-submit.pngis excluded by!**/*.pngdocs/media/ui-mcp-per-user-headers-success.pngis excluded by!**/*.pngdocs/media/ui-mcp-per-user-headers-update.pngis excluded by!**/*.pngdocs/media/ui-mcp-per-user-oauth-consent-flow.pngis excluded by!**/*.pngdocs/media/ui-mcp-per-user-oauth-flow-lazy.svgis excluded by!**/*.svgdocs/media/ui-mcp-per-user-oauth-setup.pngis excluded by!**/*.pngdocs/media/ui-mcp-sessions-table.pngis excluded by!**/*.png
📒 Files selected for processing (18)
docs/cli-agents/claude-desktop.mdxdocs/cli-agents/overview.mdxdocs/cli-agents/roo-code.mdxdocs/docs.jsondocs/mcp/auth/headers.mdxdocs/mcp/auth/none.mdxdocs/mcp/auth/oauth.mdxdocs/mcp/auth/overview.mdxdocs/mcp/auth/per-user-headers.mdxdocs/mcp/auth/per-user-oauth.mdxdocs/mcp/code-mode.mdxdocs/mcp/connecting-to-servers.mdxdocs/mcp/gateway.mdxdocs/mcp/oauth.mdxdocs/mcp/overview.mdxdocs/mcp/per-user-oauth.mdxdocs/mcp/sessions.mdxdocs/overview.mdx
💤 Files with no reviewable changes (2)
- docs/mcp/per-user-oauth.mdx
- docs/mcp/oauth.mdx
✅ Files skipped from review due to trivial changes (12)
- docs/cli-agents/overview.mdx
- docs/cli-agents/claude-desktop.mdx
- docs/mcp/auth/none.mdx
- docs/cli-agents/roo-code.mdx
- docs/mcp/auth/headers.mdx
- docs/mcp/overview.mdx
- docs/mcp/connecting-to-servers.mdx
- docs/mcp/code-mode.mdx
- docs/mcp/auth/oauth.mdx
- docs/overview.mdx
- docs/mcp/auth/overview.mdx
- docs/mcp/sessions.mdx
Pratham-Mishra04
force-pushed
the
05-21-docs_adds_per_user_mcp_connection_docs
branch
from
690fa9a to
1dbba2d
Compare
Pratham-Mishra04
force-pushed
the
05-23-fix_mcp_auth_session_reconciliation_fixes
branch
from
6a51858 to
78a9988
Compare
18 tasks
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (2)
docs/mcp/auth/per-user-oauth.mdx (1)
35-56:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winInclude API and config.json tabs alongside Web UI in setup docs.
The setup section currently has only the Web UI tab. Per coding guidelines, Mintlify MDX documentation must have Web UI / API / config.json tabs. Even though line 33 explains that per-user OAuth is "configured through the Web UI only," the tabs should still be present with explanatory content (e.g., "Not supported via API" or "Not applicable for file-based config").
As per coding guidelines: "
docs/**/*.mdx: Mintlify MDX documentation must have Web UI / API / config.json tabs; validate config.json examples against transports/config.schema.json".📋 Suggested tab structure
Add two additional tabs after the Web UI tab:
</Tab> <Tab title="API"> **Not supported.** Per-user OAuth clients must be created via the Web UI to run the initial admin OAuth flow and discover the tool list. </Tab> <Tab title="config.json"> **Not supported.** Per-user OAuth clients cannot be declared in file-based config. Use the Web UI to create the client, then reference the resulting `mcp_client_id` and `oauth_config_id` in your application code if needed. </Tab> </Tabs>🤖 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/auth/per-user-oauth.mdx` around lines 35 - 56, The docs/mcp/auth/per-user-oauth.mdx currently contains only a <Tab title="Web UI"> section; add two additional tabs (<Tab title="API"> and <Tab title="config.json">) immediately after the Web UI tab and close the <Tabs> block, each containing the suggested explanatory text ("Not supported. Per-user OAuth clients must be created via the Web UI..." for API, and "Not supported. Per-user OAuth clients cannot be declared in file-based config..." for config.json) so the MDX follows the Web UI / API / config.json requirement; also ensure any config.json examples you include (if adding examples) validate against transports/config.schema.json.docs/mcp/auth/per-user-headers.mdx (1)
178-178:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winReplace
inline-401wording withmcp_auth_requiredterminology.Lines 178 and 198 reintroduce "inline-401" framing, which conflicts with the lazy-auth model described elsewhere in this document and the stack. The document correctly uses
mcp_auth_requiredat lines 35 and 40. Suggest replacing with "inline auth URL" or "mcp_auth_requiredURL" for consistency.📝 Suggested terminology fixes
Line 178:
-When an end-user hits the inline-401 URL, they land on `/workspace/mcp-sessions/auth?flow=<id>&kind=headers`: +When an end-user opens the auth URL, they land on `/workspace/mcp-sessions/auth?flow=<id>&kind=headers`:Line 198:
-Same model as [Per-User OAuth](./per-user-oauth#identity-modes) — `user` > `vk` > `session`. A per-user-headers request with no identity is rejected with an inline-401 explaining the caller must send a VK, sign in, or set `x-bf-mcp-session-id`. +Same model as [Per-User OAuth](./per-user-oauth#identity-modes) — `user` > `vk` > `session`. A per-user-headers request with no identity is rejected with an `mcp_auth_required` payload explaining the caller must send a VK, sign in, or set `x-bf-mcp-session-id`.Also applies to: 198-198
🤖 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/auth/per-user-headers.mdx` at line 178, Replace occurrences of the string "inline-401" with the documented terminology "mcp_auth_required" (or alternatively "inline auth URL") to align with the lazy-auth model; specifically update the sentence that currently reads "inline-401 URL" to "mcp_auth_required URL" (or "inline auth URL") so it matches existing usage of `mcp_auth_required` elsewhere in this file and removes the conflicting "inline-401" framing.
🤖 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.
Duplicate comments:
In `@docs/mcp/auth/per-user-headers.mdx`:
- Line 178: Replace occurrences of the string "inline-401" with the documented
terminology "mcp_auth_required" (or alternatively "inline auth URL") to align
with the lazy-auth model; specifically update the sentence that currently reads
"inline-401 URL" to "mcp_auth_required URL" (or "inline auth URL") so it matches
existing usage of `mcp_auth_required` elsewhere in this file and removes the
conflicting "inline-401" framing.
In `@docs/mcp/auth/per-user-oauth.mdx`:
- Around line 35-56: The docs/mcp/auth/per-user-oauth.mdx currently contains
only a <Tab title="Web UI"> section; add two additional tabs (<Tab title="API">
and <Tab title="config.json">) immediately after the Web UI tab and close the
<Tabs> block, each containing the suggested explanatory text ("Not supported.
Per-user OAuth clients must be created via the Web UI..." for API, and "Not
supported. Per-user OAuth clients cannot be declared in file-based config..."
for config.json) so the MDX follows the Web UI / API / config.json requirement;
also ensure any config.json examples you include (if adding examples) validate
against transports/config.schema.json.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 3b95cb43-e2e9-4a76-9670-ba71591df3c0
⛔ Files ignored due to path filters (13)
docs/media/ui-config-mcp-disable-auto-tool-inject.pngis excluded by!**/*.pngdocs/media/ui-mcp-auth-headers-form.pngis excluded by!**/*.pngdocs/media/ui-mcp-auth-none-form.pngis excluded by!**/*.pngdocs/media/ui-mcp-auth-oauth-popup.pngis excluded by!**/*.pngdocs/media/ui-mcp-auth-per-user-headers-verify-dialog.pngis excluded by!**/*.pngdocs/media/ui-mcp-per-user-auth-flow-lazy.svgis excluded by!**/*.svgdocs/media/ui-mcp-per-user-headers-submit.pngis excluded by!**/*.pngdocs/media/ui-mcp-per-user-headers-success.pngis excluded by!**/*.pngdocs/media/ui-mcp-per-user-headers-update.pngis excluded by!**/*.pngdocs/media/ui-mcp-per-user-oauth-consent-flow.pngis excluded by!**/*.pngdocs/media/ui-mcp-per-user-oauth-flow-lazy.svgis excluded by!**/*.svgdocs/media/ui-mcp-per-user-oauth-setup.pngis excluded by!**/*.pngdocs/media/ui-mcp-sessions-table.pngis excluded by!**/*.png
📒 Files selected for processing (18)
docs/cli-agents/claude-desktop.mdxdocs/cli-agents/overview.mdxdocs/cli-agents/roo-code.mdxdocs/docs.jsondocs/mcp/auth/headers.mdxdocs/mcp/auth/none.mdxdocs/mcp/auth/oauth.mdxdocs/mcp/auth/overview.mdxdocs/mcp/auth/per-user-headers.mdxdocs/mcp/auth/per-user-oauth.mdxdocs/mcp/code-mode.mdxdocs/mcp/connecting-to-servers.mdxdocs/mcp/gateway.mdxdocs/mcp/oauth.mdxdocs/mcp/overview.mdxdocs/mcp/per-user-oauth.mdxdocs/mcp/sessions.mdxdocs/overview.mdx
💤 Files with no reviewable changes (2)
- docs/mcp/oauth.mdx
- docs/mcp/per-user-oauth.mdx
✅ Files skipped from review due to trivial changes (10)
- docs/mcp/code-mode.mdx
- docs/cli-agents/roo-code.mdx
- docs/cli-agents/overview.mdx
- docs/cli-agents/claude-desktop.mdx
- docs/mcp/auth/none.mdx
- docs/overview.mdx
- docs/mcp/connecting-to-servers.mdx
- docs/mcp/auth/overview.mdx
- docs/mcp/auth/oauth.mdx
- docs/mcp/auth/headers.mdx
🚧 Files skipped from review as they are similar to previous changes (4)
- docs/mcp/overview.mdx
- docs/docs.json
- docs/mcp/gateway.mdx
- docs/mcp/sessions.mdx
This was referenced May 27, 2026
Collaborator
Author
Merge activity
|
Pratham-Mishra04
changed the base branch from
05-23-fix_mcp_auth_session_reconciliation_fixes
to
graphite-base/3706
Pratham-Mishra04
dismissed
coderabbitai[bot]’s stale review
The base branch was changed.
Pratham-Mishra04
force-pushed
the
05-21-docs_adds_per_user_mcp_connection_docs
branch
from
1dbba2d to
01f8733
Compare
17 tasks
akshaydeo
pushed a commit
that referenced
this pull request
May 29, 2026
…model (#3706) ## Summary Introduces a new **MCP Sessions** documentation page and rewrites the per-user OAuth docs to reflect the current lazy-auth model, replacing the older consent-screen-based flow description. ## Changes - Added `docs/mcp/sessions.mdx` — a new reference page covering the MCP Sessions table, token states (`active`, `needs_reauth`, `orphaned`), pending flow rows, re-authenticate and revoke actions, identity scoping, and a troubleshooting section. - Rewrote `docs/mcp/per-user-oauth.mdx` to document the unified lazy-auth pattern used by both the MCP Gateway and LLM Gateway. Removed the old three-phase consent flow (discovery → consent screen → session token) and replaced it with the current model: identity is asserted via headers, and auth happens on the first tool call that needs an upstream token via an inline `authorize_url`. - Replaced the two-gateway identity table with a four-mode table (`user`, `vk`, `session`, `none`) that documents priority order, cross-gateway portability, and persistence behavior. Clarified that `X-Bf-User-Id` is not a public input and that `x-bf-mcp-session-id` is the correct header for session-mode identity. - Updated `docs/mcp/gateway-url.mdx` to remove the description of Bifrost acting as an OAuth 2.1 Authorization Server with `.well-known` discovery endpoints, replacing it with the current header-based identity model and a note about Claude Code's DCR probe behavior. - Updated `docs/mcp/connecting-to-servers.mdx` to reflect that the same caller identity is honored across both gateways and that auth is lazy. - Added the MCP Sessions page to the sidebar (`docs/docs.json`) and to the overview card grid (`docs/mcp/overview.mdx`). - Added a warning about `mcp_external_client_url` changes breaking already-registered upstream OAuth clients, and a note that MCP client names cannot contain hyphens. ## Type of change - [ ] Bug fix - [ ] Feature - [ ] Refactor - [x] Documentation - [ ] Chore/CI ## Affected areas - [ ] Core (Go) - [ ] Transports (HTTP) - [ ] Providers/Integrations - [ ] Plugins - [ ] UI (React) - [x] Docs ## How to test Navigate the updated docs locally and verify: 1. The MCP Sessions page renders at `mcp/sessions` and appears in the sidebar between Per-User OAuth and Tool Execution. 2. The Per-User OAuth page no longer references a consent screen, `.well-known` discovery, or Bifrost-issued session tokens. 3. The gateway URL page no longer describes a `WWW-Authenticate` 401 flow. 4. All cross-links between `per-user-oauth`, `sessions`, `gateway-url`, and `connecting-to-servers` resolve correctly. ## Screenshots/Recordings Placeholder image references are noted inline in the new and updated pages; screenshots need to be captured and added before final publication. ## Breaking changes - [ ] Yes - [x] No ## Related issues Reflects the behavioral changes shipped in Bifrost v1.5.0-prerelease2. ## Security considerations The sessions page documents that Bifrost does not call upstream `/revoke` endpoints on local revocation, and that session IDs are treated as secrets (length-only in logs, never echoed). The identity priority order (`user` > `vk` > `session`) and the scoping rules that prevent one caller from completing or revoking another caller's flow are explicitly documented. ## Checklist - [ ] I read `docs/contributing/README.md` and followed the guidelines - [ ] I added/updated tests where appropriate - [x] I updated documentation where needed - [ ] I verified builds succeed (Go and UI) - [ ] I verified the CI pipeline passes locally if applicable
18 tasks
This was referenced Jun 9, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Introduces a new MCP Sessions documentation page and rewrites the per-user OAuth docs to reflect the current lazy-auth model, replacing the older consent-screen-based flow description.
Changes
docs/mcp/sessions.mdx— a new reference page covering the MCP Sessions table, token states (active,needs_reauth,orphaned), pending flow rows, re-authenticate and revoke actions, identity scoping, and a troubleshooting section.docs/mcp/per-user-oauth.mdxto document the unified lazy-auth pattern used by both the MCP Gateway and LLM Gateway. Removed the old three-phase consent flow (discovery → consent screen → session token) and replaced it with the current model: identity is asserted via headers, and auth happens on the first tool call that needs an upstream token via an inlineauthorize_url.user,vk,session,none) that documents priority order, cross-gateway portability, and persistence behavior. Clarified thatX-Bf-User-Idis not a public input and thatx-bf-mcp-session-idis the correct header for session-mode identity.docs/mcp/gateway-url.mdxto remove the description of Bifrost acting as an OAuth 2.1 Authorization Server with.well-knowndiscovery endpoints, replacing it with the current header-based identity model and a note about Claude Code's DCR probe behavior.docs/mcp/connecting-to-servers.mdxto reflect that the same caller identity is honored across both gateways and that auth is lazy.docs/docs.json) and to the overview card grid (docs/mcp/overview.mdx).mcp_external_client_urlchanges breaking already-registered upstream OAuth clients, and a note that MCP client names cannot contain hyphens.Type of change
Affected areas
How to test
Navigate the updated docs locally and verify:
mcp/sessionsand appears in the sidebar between Per-User OAuth and Tool Execution..well-knowndiscovery, or Bifrost-issued session tokens.WWW-Authenticate401 flow.per-user-oauth,sessions,gateway-url, andconnecting-to-serversresolve correctly.Screenshots/Recordings
Placeholder image references are noted inline in the new and updated pages; screenshots need to be captured and added before final publication.
Breaking changes
Related issues
Reflects the behavioral changes shipped in Bifrost v1.5.0-prerelease2.
Security considerations
The sessions page documents that Bifrost does not call upstream
/revokeendpoints on local revocation, and that session IDs are treated as secrets (length-only in logs, never echoed). The identity priority order (user>vk>session) and the scoping rules that prevent one caller from completing or revoking another caller's flow are explicitly documented.Checklist
docs/contributing/README.mdand followed the guidelines