Enforcement Levels
Initialize Scopes
Thescopes.initialize list defines scopes required for every HTTP request to the MCP server. These are checked before the JSON-RPC payload is parsed, serving as the baseline authorization to establish an MCP connection.
Method-Level Scopes
Additional scopes can be required for specific MCP methods:initialize and method-level scopes are configured, the token must contain all of them. For example, calling tools/call requires both the initialize scopes and the tools_call scopes.
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.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:
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 (registered operations)
When your GraphQL schema uses the@requiresScopes directive on fields, the MCP server automatically extracts scope requirements for each registered operation at startup. If a tool’s underlying GraphQL operation touches fields that require specific scopes, those scopes are enforced when the tool is called.
This level only applies to registered operations exposed as tools. The execute_graphql built-in tool is checked at the next level instead.
For example, if your schema defines:
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. When an operation touches multiple fields with @requiresScopes, the MCP server computes the combined scope requirement using the Cartesian product rules. For a full explanation of how scopes combine, see the @requiresScopes directive documentation.
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 inline queries)
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.
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.
Scope Discovery with get_operation_info
The get_operation_info tool includes scope requirements in its response, allowing AI models to discover what scopes a tool needs before calling it:
Summary
| Level | When Checked | Configured Via | Failure Response |
|---|---|---|---|
| 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 a registered operation | @requiresScopes in GraphQL schema | 403 with best scope challenge |
| Runtime | execute_graphql inline queries | @requiresScopes in GraphQL schema | 403 with best scope challenge |
Token Upgrade Flow
Tokens can be upgraded on the same MCP session without reconnecting:Step-up authorization
Client obtains a new token with additional scopes from the authorization server. Requires client support for step-up authorization.
Scope Challenge Behavior
When the server returns a403 Forbidden response, the WWW-Authenticate header includes a scope parameter per RFC 6750 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:
- For each AND-group, count how many scopes the token is missing
- Pick the group with the fewest missing scopes (ties go to the first group)
(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 |
read:fact scope from the authorization server and retry.
scope_challenge_include_token_scopes
Some MCP client SDKs do not correctly accumulate scopes when performing step-up authorization - they request only the scopes from the WWW-Authenticate challenge, discarding the scopes they already had. This causes a loop where gaining a new scope loses a previous one. This is a known issue in the MCP TypeScript SDK.
To work around this, set scope_challenge_include_token_scopes: true to include the token’s existing scopes alongside the required scopes in the challenge.
| Value | Behavior | Trade-off |
|---|---|---|
false (default) | Returns only the scopes the operation requires (strict RFC 6750). | Spec-compliant and more secure, but requires the client to correctly accumulate scopes. |
true | Returns the union of the token’s existing scopes and the required scopes in the challenge. | More compatible with current MCP clients, but reveals the token’s existing scopes in the response header. |