docs(mcp): clarify that both safelisted and arbitrary operations are supported

asoorm · asoorm · commit b442200f1182 · 2026-03-13T12:55:05.000Z
diff --git a/docs/router/mcp.mdx b/docs/router/mcp.mdx
@@ -6,7 +6,7 @@ icon: "robot"
 
 For a high-level introduction, see the [MCP Gateway overview](https://wundergraph.com/mcp-gateway).
 
-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. Instead of allowing arbitrary queries, it exposes a predefined set of validated GraphQL operations as tools that AI models can discover and use.
+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.
 
 <Frame caption="Cosmo Router exposes your GraphQL Supergraph over MCP, enabling AI platforms like Cursor, Windsurf, and Claude to discover and execute operations.">
   <img
diff --git a/docs/router/mcp/oauth.mdx b/docs/router/mcp/oauth.mdx
@@ -12,14 +12,7 @@ The MCP server supports OAuth 2.1 authorization with JWKS-based JWT validation,
 
 ## Overview
 
-When OAuth is enabled, every HTTP request to the MCP server must include a valid JWT bearer token in the `Authorization` header. The server validates the token using configured JWKS providers and enforces scope requirements at multiple levels:
-
-1. **HTTP level** — `initialize` scopes are checked on every request before any JSON-RPC processing
-2. **Method level** — Additional scopes can be required for specific MCP methods (`tools/list`, `tools/call`)
-3. **Per-tool level** — Individual tools can require additional scopes derived from `@requiresScopes` directives in your GraphQL schema
-4. **Runtime level** — The `execute_graphql` tool (when enabled) checks `@requiresScopes` for the specific fields in each query at request time
-
-All scope enforcement happens at the HTTP transport level per the MCP specification, returning standard `403 Forbidden` responses with `WWW-Authenticate` headers that enable MCP clients to perform step-up authorization.
+When OAuth is enabled, every HTTP request to the MCP server must include a valid JWT bearer token in the `Authorization` header. The server validates the token using configured JWKS providers and enforces scope requirements at multiple levels. All scope enforcement happens at the HTTP transport level per the MCP specification, returning `403 Forbidden` responses with `WWW-Authenticate` headers that enable [step-up authorization](#token-upgrade-flow).
 
 ## Quick Start
 
@@ -177,99 +170,15 @@ type Query {
 
 And you have an operation `getTopSecretFacts.graphql` that queries `topSecretFacts`, calling that tool will require either `read:fact` OR `read:all` in addition to any `initialize` and `tools_call` scopes.
 
-The `@requiresScopes` directive uses **OR-of-AND** semantics:
-- `[["read:fact"], ["read:all"]]` means the token needs `read:fact` **OR** `read:all`
-- `[["read:employee", "read:private"], ["read:all"]]` means the token needs (`read:employee` **AND** `read:private`) **OR** `read:all`
-
-When a token lacks the required scopes, the server returns a `403 Forbidden` with a `WWW-Authenticate` header containing the **best** scope challenge — the scope group that requires the fewest additional scopes based on what the token already has.
-
-#### Multi-Field Scope Combination
-
-When an operation touches **multiple** fields that have `@requiresScopes`, the MCP server computes the **Cartesian product** of their OR-groups to produce the combined scope requirement for the tool. This ensures the token satisfies the requirements of every field in the operation simultaneously.
+The `@requiresScopes` directive uses OR-of-AND semantics. When an operation touches multiple fields with `@requiresScopes`, the MCP server computes the combined scope requirement using the [Cartesian product rules](/federation/directives/requiresscopes#combining-scopes-in-the-same-subgraph). For a full explanation of how scopes combine, see the [`@requiresScopes` directive documentation](/federation/directives/requiresscopes).
 
-For example, given a schema:
-
-```graphql
-type Query {
-  employee(id: ID!): Employee @requiresScopes(scopes: [["read:employee", "read:private"], ["read:all"]])
-  topSecretFacts: [Fact!]! @requiresScopes(scopes: [["read:fact"], ["read:all"]])
-}
-```
-
-And an operation that queries **both** fields:
-
-```graphql
-"""
-Get an employee's profile and top secret facts.
-"""
-query GetEmployeeWithFacts($id: ID!) {
-  employee(id: $id) { id name }
-  topSecretFacts { id description }
-}
-```
-
-The per-field requirements are:
-- `employee`: `(read:employee AND read:private) OR (read:all)`
-- `topSecretFacts`: `(read:fact) OR (read:all)`
-
-The Cartesian product combines every group from the first field with every group from the second field, deduplicating within each combination:
-
-| employee group | topSecretFacts group | Combined AND-group |
-| --- | --- | --- |
-| `read:employee`, `read:private` | `read:fact` | `read:employee`, `read:private`, `read:fact` |
-| `read:employee`, `read:private` | `read:all` | `read:employee`, `read:private`, `read:all` |
-| `read:all` | `read:fact` | `read:all`, `read:fact` |
-| `read:all` | `read:all` | `read:all` |
-
-The resulting combined requirement for the tool is:
-
-```
-(read:employee AND read:private AND read:fact)
-  OR (read:employee AND read:private AND read:all)
-  OR (read:all AND read:fact)
-  OR (read:all)
-```
-
-A token satisfying **any one** of these four groups can call the tool.
-
-#### Smart Scope Challenge Selection
-
-When a token lacks the required scopes, the server doesn't just return an arbitrary scope group — it picks the **best** one based on what the token already has. The algorithm:
-
-1. For each AND-group, count how many scopes the token is **missing**
-2. If any group has 0 missing, the token is sufficient (no challenge needed)
-3. Pick the group with the **fewest missing** scopes (ties go to the first group)
-
-Using the combined requirement above, if a client presents a token with scopes `read:employee read:private`:
-
-| AND-group | Missing scopes | Count |
-| --- | --- | --- |
-| `read:employee`, `read:private`, `read:fact` | `read:fact` | 1 |
-| `read:employee`, `read:private`, `read:all` | `read:all` | 1 |
-| `read:all`, `read:fact` | `read:all`, `read:fact` | 2 |
-| `read:all` | `read:all` | 1 |
-
-Three groups tie with 1 missing scope. The server picks the first: `read:employee`, `read:private`, `read:fact`. The 403 response includes:
-
-```
-WWW-Authenticate: Bearer error="insufficient_scope", scope="read:employee read:private read:fact"
-```
-
-The client can then request the additional `read:fact` scope from the authorization server and retry.
-
-<Info>
-  The `scope` parameter in the `WWW-Authenticate` header contains the **complete AND-group** (not just the missing scopes), per RFC 6750. This tells the client exactly which scopes are needed for the operation. If `scope_challenge_include_token_scopes` is enabled, the token's existing scopes are also included — see [Scope Challenge Behavior](#scope-challenge-behavior).
-</Info>
-
-<Info>
-  Per-tool scopes are computed at startup (and on config reload) by analyzing which fields each operation touches. This means scope requirements are enforced at the HTTP level before the GraphQL query is executed, with zero runtime overhead per request.
-</Info>
+Per-tool scopes are computed at startup (and on config reload), so they are enforced at the HTTP level with zero runtime overhead per request.
 
 ### Runtime Scopes (`execute_graphql`)
 
 When `enable_arbitrary_operations` is enabled, the `execute_graphql` tool allows AI models to craft custom GraphQL queries. Since the server cannot know which fields will be queried ahead of time, scope checking happens at request time by parsing the GraphQL query and extracting `@requiresScopes` requirements for the fields it references.
 
-This runtime check uses the same OR-of-AND semantics and smart challenge selection as per-tool scopes. If the token lacks required scopes, the server returns a `403 Forbidden` with an appropriate scope challenge before the query is executed.
+This runtime check uses the same [OR-of-AND semantics](/federation/directives/requiresscopes) and smart challenge selection as per-tool scopes. If the token lacks required scopes, the server returns a `403 Forbidden` with an appropriate scope challenge before the query is executed.
 
 <Info>
   If the GraphQL query cannot be parsed, the request is passed through to the GraphQL engine, which handles the error. Scope checking is best-effort and does not block malformed queries.
@@ -287,7 +196,7 @@ This runtime check uses the same OR-of-AND semantics and smart challenge selecti
 
 ## `get_operation_info` and Scope Discovery
 
-The built-in `get_operation_info` tool includes scope requirements in its response when a tool's underlying operation has `@requiresScopes` directives. This allows AI models to understand what scopes are needed before attempting to call a tool:
+The `get_operation_info` tool includes scope requirements in its response, allowing AI models to discover what scopes a tool needs before calling it:
 
 ```
 Required Scopes (OR-of-AND):
@@ -296,26 +205,38 @@ Required Scopes (OR-of-AND):
   - read:all
 ```
 
-This enables AI assistants to inform users about required permissions before attempting operations that may fail due to insufficient scopes.
-
 ## Token Upgrade Flow
 
-Because authentication happens at the HTTP level, tokens can be upgraded **on the same MCP session** without reconnecting:
-
-1. A client connects with a token that has `mcp:connect` scope
-2. The client calls `tools/call` and receives a `403 Forbidden` with `insufficient_scope`
-3. The client obtains a new token with additional scopes from the authorization server
-4. The client retries with the new token on the same session (same `Mcp-Session-Id`)
+Tokens can be upgraded **on the same MCP session** without reconnecting:
 
-This step-up authorization pattern is fully supported and does not require re-establishing the MCP session. The flow is the same regardless of which scope level triggered the 403 (method, per-tool, or runtime).
+1. Client connects with a token that has `mcp:connect` scope
+2. Client calls `tools/call` and receives `403 Forbidden` with `insufficient_scope`
+3. Client obtains a new token with additional scopes from the authorization server
+4. Client retries with the new token on the same session (same `Mcp-Session-Id`)
 
 ## Scope Challenge Behavior
 
-When the server returns a `403 Forbidden` response, the `WWW-Authenticate` header includes a `scope` parameter telling the client which scopes to request. The `scope_challenge_include_token_scopes` option controls how this parameter is built.
+When the server returns a `403 Forbidden` response, the `WWW-Authenticate` header includes a `scope` parameter per [RFC 6750](https://datatracker.ietf.org/doc/rfc6750/) telling the client which scopes to request.
+
+For per-tool and runtime challenges where multiple scope groups can satisfy the requirement (OR-of-AND), the server selects the **best** group — the one requiring the fewest additional scopes based on what the token already has:
+
+1. For each AND-group, count how many scopes the token is **missing**
+2. Pick the group with the **fewest missing** scopes (ties go to the first group)
+
+For example, suppose a tool requires `(read:employee AND read:private AND read:fact) OR (read:all)` and a client presents a token with scopes `read:employee read:private`:
+
+| AND-group | Missing scopes | Count |
+| --- | --- | --- |
+| `read:employee`, `read:private`, `read:fact` | `read:fact` | 1 |
+| `read:all` | `read:all` | 1 |
+
+Both groups have 1 missing scope. The server picks the first, returning the **complete AND-group** (not just the missing scopes):
 
-Per [RFC 6750](https://datatracker.ietf.org/doc/rfc6750/), the `scope` parameter should contain the scopes *"required for accessing the requested resource"*. The server returns only the scopes needed for the specific operation that failed — not all scopes the server supports.
+```
+WWW-Authenticate: Bearer error="insufficient_scope", scope="read:employee read:private read:fact"
+```
 
-For per-tool and runtime scope challenges where multiple scope groups can satisfy the requirement (OR-of-AND), the server selects the **best** group: the one requiring the fewest additional scopes based on what the token already has. This minimizes the authorization step-up needed.
+The client can then request the additional `read:fact` scope from the authorization server and retry.
 
 ### `scope_challenge_include_token_scopes`
 
