docs(mcp): restructure MCP docs and add OAuth 2.1 authorization (ENG-9125)#2690
Merged
docs(mcp): restructure MCP docs and add OAuth 2.1 authorization (ENG-9125)#2690
Conversation
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughReorganizes docs navigation to add a grouped "MCP Gateway" section, converts the MCP landing page into a concise overview, and adds five new MCP reference pages (quickstart, operations, configuration, IDE setup, OAuth). Also normalizes JSON formatting in Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
![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: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs-website/router/mcp/configuration.mdx`:
- Around line 104-107: The Info box incorrectly states that session.stateless is
reserved and that the server always runs stateful; update or remove that Info
block so it accurately reflects the real behavior: session.stateless is an
active setting (default true) which causes the MCP server to operate in
stateless mode when true; locate the Info element in configuration.mdx and
either replace its text to state that session.stateless defaults to true and
enables stateless mode, or remove the Info box entirely if no extra note is
needed, ensuring mention of the configuration key session.stateless and its
default behavior is consistent with the rest of the doc.
In `@docs-website/router/mcp/ide-setup.mdx`:
- Around line 13-17: Update the docs to stop saying the MCP server "forwards all
headers" and instead state that it forwards most client headers but excludes a
set of filtered headers defined in headers.SkippedHeaders (see the connectrpc
handler implementation that filters headers in the handler code path),
mentioning that hop-by-hop/custom excluded headers are skipped; reference
headers.SkippedHeaders and the connectrpc handler function when editing the text
so readers know where the filtering occurs.
In `@docs-website/router/mcp/operations.mdx`:
- Around line 125-129: The docs paragraph is wrong: the implementation (check of
operationToolName against registeredTools and reservedToolNames in server.go
which logs via s.logger.Error with op.Name and operationToolName and then
continue) skips colliding operations rather than prefixing them; update the
documentation text to state that colliding operations are skipped and an error
is logged (referencing the behavior tied to operationToolName,
registeredTools/reservedToolNames, s.logger.Error and the continue path) so docs
match the actual server behavior.
🪄 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: 1cdaf0a0-f87d-41d6-a321-7c642670c50d
📒 Files selected for processing (7)
docs-website/docs.jsondocs-website/router/mcp.mdxdocs-website/router/mcp/configuration.mdxdocs-website/router/mcp/ide-setup.mdxdocs-website/router/mcp/oauth.mdxdocs-website/router/mcp/operations.mdxdocs-website/router/mcp/quickstart.mdx
asoorm
force-pushed
the
ahmet/eng-9125-mcp-docs-restructure-oauth
branch
from
7ea8d9c to
af21d71
Compare
asoorm
force-pushed
the
ahmet/eng-9125-mcp-docs-restructure-oauth
branch
from
af21d71 to
370d332
Compare
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs-website/router/mcp.mdx (1)
9-9: Tighten wording for clarity in the intro sentence.The phrase “operations, or capabilities as MCP tools” reads ambiguously. Consider simplifying to make the two exposure modes explicit.
✏️ Suggested wording
-WunderGraph's MCP Gateway is a feature of the Cosmo Router that enables AI models to interact with your GraphQL APIs using a structured protocol. We can expose a predefined set of safelisted operations, or capabilities as MCP tools, or allow agents to execute GraphQL directly. +WunderGraph's MCP Gateway is a feature of the Cosmo Router that enables AI models to interact with your GraphQL APIs using a structured protocol. It can either expose a predefined set of safelisted operations as MCP tools or allow agents to execute GraphQL directly.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs-website/router/mcp.mdx` at line 9, Rewrite the ambiguous intro sentence to clearly state the two exposure modes: expose a predefined set of safelisted operations as MCP tools, or allow agents to execute GraphQL directly; replace the current phrase “operations, or capabilities as MCP tools” with a concise construction such as “expose a predefined set of safelisted operations as MCP tools, or allow agents to execute GraphQL directly” so the difference between the two modes is explicit.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@docs-website/router/mcp.mdx`:
- Line 9: Rewrite the ambiguous intro sentence to clearly state the two exposure
modes: expose a predefined set of safelisted operations as MCP tools, or allow
agents to execute GraphQL directly; replace the current phrase “operations, or
capabilities as MCP tools” with a concise construction such as “expose a
predefined set of safelisted operations as MCP tools, or allow agents to execute
GraphQL directly” so the difference between the two modes is explicit.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: ad9a1d14-c2f8-4264-8975-d91e523875e2
📒 Files selected for processing (7)
docs-website/docs.jsondocs-website/router/mcp.mdxdocs-website/router/mcp/configuration.mdxdocs-website/router/mcp/ide-setup.mdxdocs-website/router/mcp/oauth.mdxdocs-website/router/mcp/operations.mdxdocs-website/router/mcp/quickstart.mdx
✅ Files skipped from review due to trivial changes (6)
- docs-website/router/mcp/ide-setup.mdx
- docs-website/router/mcp/quickstart.mdx
- docs-website/docs.json
- docs-website/router/mcp/operations.mdx
- docs-website/router/mcp/configuration.mdx
- docs-website/router/mcp/oauth.mdx
asoorm
force-pushed
the
ahmet/eng-9125-mcp-docs-restructure-oauth
branch
from
370d332 to
915a4d4
Compare
asoorm
force-pushed
the
ahmet/eng-9125-mcp-docs-restructure-oauth
branch
from
915a4d4 to
9bab331
Compare
Contributor
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs-website/router/mcp.mdx (1)
7-18:⚠️ Potential issue | 🟠 MajorUpdate the MCP specification version to the latest available.
The specification version
2025-06-18is real but not the latest. Version2025-11-25is the current latest version of the MCP specification. Update line 18 to reference2025-11-25instead, and remove or correct the claim that it is the "latest" supported version if the older version is still actively supported.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs-website/router/mcp.mdx` around lines 7 - 18, Update the MCP specification version referenced in the Note from `2025-06-18` to `2025-11-25` and adjust the wording in the Note element (the string "We support only the latest MCP specification `2025-06-18` with Streamable HTTP support.") so it no longer incorrectly claims `2025-06-18` is the latest; either state that the docs support `2025-11-25` or list both versions if older versions remain supported, making the Note text reflect the correct supported spec(s).
🧹 Nitpick comments (1)
docs-website/router/mcp.mdx (1)
79-81: Clarify the GraphQL spec version reference for block string descriptions.Block string descriptions (triple-quoted strings) were introduced in the June 2018 GraphQL specification, not September 2025. The phrase "Using the September 2025 GraphQL spec" on line 81 is misleading. Either reference the June 2018 spec where the feature originated, or use "GraphQL spec" without a date to avoid implying this is a recently added feature.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs-website/router/mcp.mdx` around lines 79 - 81, The documentation incorrectly attributes block string descriptions to the "September 2025 GraphQL spec"; update the "Self-documenting operations" line containing the phrase "Using the September 2025 GraphQL spec" to either reference the correct origin "June 2018 GraphQL spec" or remove the date and use "the GraphQL spec" to avoid implying it's a recent addition—edit the text under the "Self-documenting operations" bullet accordingly.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In `@docs-website/router/mcp.mdx`:
- Around line 7-18: Update the MCP specification version referenced in the Note
from `2025-06-18` to `2025-11-25` and adjust the wording in the Note element
(the string "We support only the latest MCP specification `2025-06-18` with
Streamable HTTP support.") so it no longer incorrectly claims `2025-06-18` is
the latest; either state that the docs support `2025-11-25` or list both
versions if older versions remain supported, making the Note text reflect the
correct supported spec(s).
---
Nitpick comments:
In `@docs-website/router/mcp.mdx`:
- Around line 79-81: The documentation incorrectly attributes block string
descriptions to the "September 2025 GraphQL spec"; update the "Self-documenting
operations" line containing the phrase "Using the September 2025 GraphQL spec"
to either reference the correct origin "June 2018 GraphQL spec" or remove the
date and use "the GraphQL spec" to avoid implying it's a recent addition—edit
the text under the "Self-documenting operations" bullet accordingly.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: aed11b06-d125-4c1c-812a-ffe5b1149033
📒 Files selected for processing (7)
docs-website/docs.jsondocs-website/router/mcp.mdxdocs-website/router/mcp/configuration.mdxdocs-website/router/mcp/ide-setup.mdxdocs-website/router/mcp/oauth.mdxdocs-website/router/mcp/operations.mdxdocs-website/router/mcp/quickstart.mdx
✅ Files skipped from review due to trivial changes (5)
- docs-website/router/mcp/quickstart.mdx
- docs-website/router/mcp/ide-setup.mdx
- docs-website/router/mcp/configuration.mdx
- docs-website/router/mcp/oauth.mdx
- docs-website/router/mcp/operations.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- docs-website/docs.json
shamashel
reviewed
Mar 26, 2026
Contributor
shamashel
left a comment
shamashel
left a comment
There was a problem hiding this comment.
Loving this in general. Getting subpages really makes it feel like MCP has first-class support.
Left a couple comments, but this is really good!
…9125) Restructure MCP docs from single page into multi-page architecture (overview, quickstart, operations, configuration, oauth, ide-setup). Add OAuth 2.1 scope enforcement docs with JWKS config, multi-level scope gates, step-up authorization, and RFC 9728 metadata discovery. Ported from wundergraph/cosmo-docs#260.
Split the single OAuth page into four pages by documentation type: - Overview (explanation): how OAuth works in MCP context - Quickstart (tutorial): step-by-step setup with verification - Scope Enforcement (explanation): multi-level additive model - Configuration Reference (reference): config tables, env vars, error formats This addresses customer feedback that the OAuth docs were detailed but complex, mixing reference, explanation, and how-to content on a single page.
asoorm
force-pushed
the
ahmet/eng-9125-mcp-docs-restructure-oauth
branch
from
17303ec to
598cad4
Compare
Most MCP clients (including Claude Code) do not yet support 403 insufficient_scope step-up re-authorization. Document the limitation with workarounds and link to anthropics/claude-code#44652.
endigma
requested changes
Apr 17, 2026
…ure-oauth' into ahmet/eng-9125-mcp-docs-restructure-oauth
asoorm
force-pushed
the
ahmet/eng-9125-mcp-docs-restructure-oauth
branch
from
aa80f1c to
efc872e
Compare
endigma
approved these changes
Apr 20, 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
3 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
WWW-Authenticatechallenges, OR-of-AND scope semantics, RFC 9728 discoveryrouter/pkg/mcpserver/implementation and fix inaccuraciesPorted from wundergraph/cosmo-docs#260.
Test plan
Summary by CodeRabbit