docs(mcp): comprehensive OAuth scope enforcement documentation

Update MCP docs to cover multi-level scope enforcement including
per-tool scopes from @requiresScopes, built-in tool scopes, runtime
execute_graphql scope checking, scope challenge behavior, and
RFC 9728 metadata with scopes_supported discovery.

Author: asoorm

docs/router/mcp.mdx

@@ -244,7 +244,10 @@ storage_providers:
 | `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](#scope-challenge-behavior). | `false` |
 | `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 scopes from `@requiresScopes` are enforced additively. | `[]` |
+| `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. | `[]` |
+| `oauth.scopes.execute_graphql` | Scopes required to call the `execute_graphql` built-in tool. Additive to `tools_call`. Only relevant when `enable_arbitrary_operations` is `true`. | `[]` |
+| `oauth.scopes.get_operation_info` | Scopes required to call the `get_operation_info` built-in tool. Additive to `tools_call`. | `[]` |
+| `oauth.scopes.get_schema`   | Scopes required to call the `get_schema` built-in tool. Additive to `tools_call`. Only relevant when `expose_schema` is `true`. | `[]` |
 | `oauth.jwks`                 | List of JWKS providers for JWT verification. Supports remote JWKS URLs or symmetric secrets. See [JWKS Configuration](#jwks-configuration). | `[]` |
 | `server.base_url`            | The public base URL of the MCP server. **Required when OAuth is enabled.** Used for the RFC 9728 metadata endpoint and `resource_metadata` in `WWW-Authenticate` headers. Set this to your externally-reachable URL when behind a reverse proxy or load balancer. | - |
 
@@ -508,8 +511,9 @@ Scopes are enforced at multiple levels, all at the HTTP transport layer per the
 HTTP Request
   → Initialize scopes (all requests)
     → Method scopes (tools/list, tools/call)
-      → Per-tool scopes (from @requiresScopes on operation fields)
-        → Runtime scopes (execute_graphql only, per-query)
+      → Built-in tool scopes (execute_graphql, get_schema, get_operation_info)
+        → Per-tool scopes (from @requiresScopes on operation fields)
+          → Runtime scopes (execute_graphql only, per-query)
 ```
 
 #### Initialize Scopes (HTTP Level)
@@ -542,6 +546,27 @@ When both `initialize` and method-level scopes are configured, the token must co
   Scopes in the JWT must be provided as a **space-separated string** in the `scope` claim (per OAuth 2.0 convention). Array-format scope claims are not supported.
 </Info>
 
+#### Built-in Tool Scopes
+
+The MCP server provides three built-in tools: `execute_graphql`, `get_operation_info`, and `get_schema`. Each can have its own scope requirements, configured independently from `tools_call`:
+
+```yaml
+oauth:
+  scopes:
+    tools_call:
+      - "mcp:tools:execute"       # Base gate for any tool
+    execute_graphql:
+      - "mcp:graphql:execute"     # Additional scope for execute_graphql
+    get_operation_info:
+      - "mcp:ops:read"            # Additional scope for get_operation_info
+    get_schema:
+      - "mcp:schema:read"         # Additional scope for get_schema
+```
+
+Built-in tool scopes are **additive** to `tools_call` — the token must satisfy both. If `tools_call` is empty, only the built-in tool scope is checked.
+
+Scopes for `execute_graphql` are only relevant when `enable_arbitrary_operations: true`, and scopes for `get_schema` are only relevant when `expose_schema: true`. When the corresponding feature is disabled, the tool is not registered and its scopes are excluded from the `scopes_supported` metadata.
+
 #### Per-Tool Scopes (from `@requiresScopes`)
 
 When your GraphQL schema uses the `@requiresScopes` directive on fields, the MCP server automatically extracts scope requirements for each tool at startup. If a tool's underlying GraphQL operation touches fields that require specific scopes, those scopes are enforced when the tool is called.
@@ -583,6 +608,7 @@ This runtime check uses the same OR-of-AND semantics and smart challenge selecti
 | --- | --- | --- | --- |
 | Initialize | Every HTTP request | `oauth.scopes.initialize` | 403 with required scopes |
 | Method | `tools/list`, `tools/call` | `oauth.scopes.tools_list`, `oauth.scopes.tools_call` | 403 with required scopes |
+| Built-in tool | `tools/call` for built-in tools | `oauth.scopes.execute_graphql`, `oauth.scopes.get_schema`, `oauth.scopes.get_operation_info` | 403 with required scopes |
 | Per-tool | `tools/call` for specific tool | `@requiresScopes` in GraphQL schema | 403 with best scope challenge |
 | Runtime | `execute_graphql` calls | `@requiresScopes` in GraphQL schema | 403 with best scope challenge |
 
@@ -732,6 +758,8 @@ mcp:
     base_url: "https://mcp.example.com"
   graph_name: "my-graph"
   exclude_mutations: true
+  enable_arbitrary_operations: true  # Enables execute_graphql tool
+  expose_schema: true                # Enables get_schema tool
   oauth:
     enabled: true
     authorization_server_url: "https://auth.example.com"
@@ -743,6 +771,13 @@ mcp:
         - "mcp:tools:read"
       tools_call:
         - "mcp:tools:execute"
+      # Built-in tool scopes (additive to tools_call)
+      execute_graphql:
+        - "mcp:graphql:execute"
+      get_schema:
+        - "mcp:schema:read"
+      get_operation_info:
+        - "mcp:ops:read"
     jwks:
       - url: "https://auth.example.com/.well-known/jwks.json"
         audiences: