docs(mcp): address PR review comments

Author: asoorm

docs-website/router/mcp.mdx

@@ -1,6 +1,7 @@
 ---
 title: 'MCP Gateway'
-description: 'Connect AI models to your GraphQL APIs using the Model Context Protocol. The Cosmo Router MCP Gateway lets AI platforms like Claude, Cursor, and Windsurf discover and execute your operations through a secure, standardized interface.'
+description: 'Connect AI models to your GraphQL APIs using the Model Context Protocol.'
+keywords: ['MCP', 'Model Context Protocol', 'MCP Gateway', 'Claude', 'Cursor', 'Windsurf', 'AI', 'GraphQL']
 icon: 'robot'
 ---
 

docs-website/router/mcp/configuration.mdx

@@ -38,7 +38,7 @@ storage_providers:
 | `exclude_mutations`           | Whether to exclude mutation operations from being exposed                                                                                                                                                                                                                    | `false`          |
 | `enable_arbitrary_operations` | Enables the `execute_graphql` built-in tool, allowing clients to run arbitrary GraphQL operations beyond the pre-defined operation set.                                                                                                                                      | `false`          |
 | `expose_schema`               | Enables the `get_schema` built-in tool, exposing the full GraphQL schema to MCP clients.                                                                                                                                                                                     | `false`          |
-| `omit_tool_name_prefix`       | When enabled, MCP tool names omit the `execute_operation_` prefix. For example, `GetUser` becomes `get_user` instead of `execute_operation_get_user`. See [Operations — Omitting the Tool Name Prefix](/router/mcp/operations#omitting-the-tool-name-prefix).                | `false`          |
+| `omit_tool_name_prefix`       | When enabled, MCP tool names omit the `execute_operation_` prefix. For example, `GetUser` becomes `get_user` instead of `execute_operation_get_user`. See [Operations - Omitting the Tool Name Prefix](/router/mcp/operations#omitting-the-tool-name-prefix).                | `false`          |
 
 For OAuth-specific configuration, see [OAuth 2.1 Authorization](/router/mcp/oauth/overview).
 
@@ -93,7 +93,7 @@ To configure sticky sessions:
 2. Clients must include that value in subsequent requests as the `Mcp-Session-Id` request header
 3. Your load balancer or reverse proxy must route requests with the same `Mcp-Session-Id` to the same instance
 
-For details, see your load balancer or reverse proxy documentation (e.g., [F5 NGINX Plus — MCP Session Affinity](https://community.f5.com/kb/technicalarticles/mcp-session-affinity-with-f5-nginx-plus/341961)).
+For details, see your load balancer or reverse proxy documentation (e.g., [F5 NGINX Plus - MCP Session Affinity](https://community.f5.com/kb/technicalarticles/mcp-session-affinity-with-f5-nginx-plus/341961)).
 
 ## CORS
 

docs-website/router/mcp/ide-setup.mdx

@@ -1,6 +1,7 @@
 ---
 title: 'IDE & AI Tool Setup'
-description: 'Connect Claude Desktop, Cursor, Windsurf, VS Code, and other AI tools to your MCP Gateway. Includes header forwarding for authentication and tracing.'
+description: 'Connect AI tools to your MCP Gateway. Includes header forwarding for authentication and tracing.'
+keywords: ['MCP', 'Claude Desktop', 'Cursor', 'Windsurf', 'VS Code', 'IDE', 'AI tools']
 icon: 'display-code'
 ---
 
@@ -10,14 +11,14 @@ This guide covers how to connect popular AI tools to your Cosmo Router MCP serve
 
 <Info>Available since Router [0.260.0](https://github.com/wundergraph/cosmo/releases/tag/router%400.260.0)</Info>
 
-The MCP server forwards most client headers to the Router — including authorization, custom, and tracing headers — but skips hop-by-hop and content negotiation headers (defined in [`headers.SkippedHeaders`](https://github.com/wundergraph/cosmo/blob/main/router/internal/headers/headers.go)). This allows you to:
+The MCP server forwards most client headers to the Router - including authorization, custom, and tracing headers - but skips hop-by-hop and content negotiation headers (defined in [`headers.SkippedHeaders`](https://github.com/wundergraph/cosmo/blob/main/router/internal/headers/headers.go)). This allows you to:
 
 - Leverage all authentication and authorization capabilities of your Cosmo Router
 - Pass custom headers for tracing, debugging, or application-specific purposes
 - Maintain consistent security and observability across all API consumers
 
 <Info>
-  Headers are forwarded through the chain: MCP Client → MCP Server → Router → Subgraphs. The router's
+  Headers are forwarded through the chain: MCP Client -> MCP Server -> Router -> Subgraphs. The router's
   [header forwarding rules](/router/proxy-capabilities/subgraph-request-header-operations) determine what ultimately
   reaches your subgraphs.
 </Info>
@@ -45,7 +46,7 @@ Go to **Settings** > **Tools & Integrations** > **MCP Servers** and add the foll
 }
 ```
 
-All `headers` fields are optional — include only what your setup requires.
+All `headers` fields are optional - include only what your setup requires.
 
 ### Claude Desktop
 

docs-website/router/mcp/oauth/configuration.mdx

@@ -11,7 +11,7 @@ icon: 'sliders-up'
 | `oauth.enabled`                              | Enable OAuth 2.1 / JWKS-based authentication for the MCP server                                                                                                                                                               | `false` |
 | `oauth.authorization_server_url`             | Base URL of the OAuth 2.0 authorization server. Advertised via the [RFC 9728 metadata endpoint](#rfc-9728-protected-resource-metadata) so clients can discover authorization endpoints.                                       | -       |
 | `oauth.scope_challenge_include_token_scopes` | When `true`, includes the token's existing scopes in the `scope` parameter of 403 responses. Works around MCP SDK scope accumulation bugs. See [Scope Challenge Behavior](/router/mcp/oauth/scopes#scope-challenge-behavior). | `false` |
-| `oauth.max_scope_combinations`               | Upper limit on scope combinations produced when computing the Cartesian product of `@requiresScopes` across fields. Increase for complex RBAC configurations. | `2048`  |
+| `oauth.max_scope_combinations`               | Maximum scope combinations computed per operation. Raise for schemas with many overlapping `@requiresScopes`.                                                                                                                 | `2048`  |
 | `oauth.scopes.initialize`                    | Scopes required for **all** HTTP requests (checked before JSON-RPC parsing). This is the baseline scope needed to establish an MCP connection.                                                                                | `[]`    |
 | `oauth.scopes.tools_list`                    | Scopes required for the `tools/list` MCP method.                                                                                                                                                                              | `[]`    |
 | `oauth.scopes.tools_call`                    | Scopes required for the `tools/call` MCP method (any tool invocation). Per-tool and built-in tool scopes are enforced additively.                                                                                             | `[]`    |
@@ -55,7 +55,7 @@ For development or testing, you can use a shared symmetric secret instead of a r
 oauth:
   jwks:
     - secret: 'your-shared-secret'
-      symmetric_algorithm: 'HS256' # HS256, HS384, or HS512
+      symmetric_algorithm: 'HS256' # HS256, HS384, or HS512. For other algorithms, use a remote JWKS URL.
       header_key_id: 'my-key-id'
 ```
 
@@ -76,7 +76,9 @@ Returned when the token is missing, invalid, expired, or signature verification
 
 ```
 HTTP/1.1 401 Unauthorized
-WWW-Authenticate: Bearer realm="mcp", scope="mcp:connect", resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource/mcp"
+WWW-Authenticate: Bearer realm="mcp",
+                  scope="mcp:connect",
+                  resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource/mcp"
 ```
 
 The `scope` parameter contains the `initialize` scopes (minimum scopes needed to connect). The `resource_metadata` URL points to the [RFC 9728 metadata endpoint](#rfc-9728-protected-resource-metadata) for OAuth discovery.
@@ -89,20 +91,26 @@ Returned when the token is valid but lacks required scopes. The exact `scope` pa
 
 ```
 HTTP/1.1 403 Forbidden
-WWW-Authenticate: Bearer error="insufficient_scope", scope="mcp:tools:execute", resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource/mcp", error_description="missing required scopes: mcp:tools:execute"
+WWW-Authenticate: Bearer error="insufficient_scope",
+                  scope="mcp:tools:execute",
+                  resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource/mcp",
+                  error_description="missing required scopes: mcp:tools:execute"
 ```
 
 **Per-tool rejection** (e.g., calling a tool that requires `read:fact`):
 
 ```
 HTTP/1.1 403 Forbidden
-WWW-Authenticate: Bearer error="insufficient_scope", scope="read:fact", resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource/mcp", error_description="insufficient scopes for tool execute_operation_get_top_secret_facts"
+WWW-Authenticate: Bearer error="insufficient_scope",
+                  scope="read:fact",
+                  resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource/mcp",
+                  error_description="insufficient scopes for tool execute_operation_get_top_secret_facts"
 ```
 
 The `scope` parameter always contains only the scopes needed for the specific operation that failed (unless `scope_challenge_include_token_scopes` is enabled).
 
 <Info>
-  Per the MCP specification, HTTP-level authentication failures return only HTTP status codes and headers — no JSON-RPC
+  Per the MCP specification, HTTP-level authentication failures return only HTTP status codes and headers - no JSON-RPC
   response body is included.
 </Info>
 
@@ -146,7 +154,7 @@ The `scopes_supported` field is **automatically computed** as the union of:
 The router performs startup validation when OAuth is enabled:
 
 - If `oauth.jwks` is empty, the router exits with a fatal error to prevent starting an unprotected endpoint
-- If `server.base_url` is empty, the router exits with a fatal error because it is required for RFC 9728 metadata discovery
+- If `server.base_url` is empty, the router exits with a fatal error because it is required for [RFC 9728](https://datatracker.ietf.org/doc/rfc9728/) metadata discovery
 
 ## Full Configuration Example
 

docs-website/router/mcp/oauth/overview.mdx

@@ -16,7 +16,7 @@ All scope enforcement happens at the HTTP transport level per the MCP specificat
 
 ## Token Validation
 
-The MCP server validates JWT bearer tokens using JWKS (JSON Web Key Sets). You can configure one or more JWKS providers — either remote JWKS URLs (for production with providers like Keycloak, Auth0, Okta) or symmetric secrets (for development and testing).
+The MCP server validates JWT bearer tokens using JWKS (JSON Web Key Sets). You can configure one or more JWKS providers - either remote JWKS URLs (for production with providers like Keycloak, Auth0, Okta) or symmetric secrets (for development and testing).
 
 The MCP OAuth config uses the **same JWKS format** as the router's top-level [authentication configuration](/router/authentication-and-authorization), though it is configured independently. You can point the MCP JWKS to the same JWKS URL as your router authentication, or to a different identity provider entirely.