OAuth 2.1 Scoping for MCP Tool Servers

Proper scope design prevents agents from accessing unrelated tools even with valid tokens.

· 8 min read
Cover illustration for “OAuth 2.1 Scoping for MCP Tool Servers”
Agentic Protocol Internals · October 23, 2026 · 8 min read · 1,895 words

OAuth 2.1 scoping for MCP tool servers sets whether a valid token gives an agent only the access it needs or lets it use unrelated tools. The authorization flow establishes a trusted exchange, but scope design sets its practical limits. Coarse scopes can recreate the broad permissions of API-key sprawl inside short-lived tokens.

Why the MCP authorization spec uses OAuth 2.1 and where scope fits in the design

MCP maps three OAuth roles onto its architecture. The MCP server is the resource server, the agent or its host application is the OAuth client, and a separate authorization server handles user interaction and issues tokens. Issuance remains separate even when the services are co-hosted. The tokens are short-lived, audience-bound, and scoped to one MCP server, so they work differently from long-lived API keys. Within that structure, the specification leaves the mapping from scopes to permitted tool calls to the implementer.

What the current MCP authorization flow actually does, step by step

The exchange begins when the server returns a 401 with a Protected Resource Metadata pointer. The client fetches that document to discover the authorization server and the resource’s supported scopes. The scopes_supported array makes scope design visible early. The client then fetches the authorization server’s metadata to learn its endpoints and PKCE support. If code_challenge_methods_supported is absent, the client must stop.

Client registration establishes the identity used in the authorization exchange. Under the current specification, the preferred path is a Client ID Metadata Document, or CIMD, where the client_id is an HTTPS URL serving client metadata as JSON. Dynamic Client Registration is deprecated but retained for backward compatibility. VS Code supplies a URL hosted on vscode.dev, while Claude Code supplies one hosted on claude.ai. The client then opens /authorize with PKCE using S256 and the resource parameter set to the server’s canonical URI. The authorization server returns a short-lived access token and a refresh token.

Every subsequent request includes the bearer token. The server validates audience, issuer, expiry, and scope on each call. The July 2026 revision removed protocol-level sessions and the Mcp-Session-Id header, so each request now describes itself. CVE-2026-16496 illustrates why that distinction is consequential. The Terraform MCP server’s per-session credential cache was keyed solely on the MCP session ID, without binding it to the token that created it, so a leaked identifier could expose a user’s full tool authority.

Why validating a token is not the same as enforcing least privilege

A token can pass audience, issuer, and expiry checks while granting access to every tool on the server. Even a scope check on every request cannot fix a scope that allows too much. A flat mcp.write scope can satisfy the specification’s checks while allowing a compromised or misdirected agent to invoke write-capable tools it never needed.

The specification requires enforcement but does not prescribe the permissions that enforcement should distinguish. If unrelated write operations all accept the same scope, the server has no scope-level basis for separating them. The parallel to API-key sprawl is direct. A broadly privileged API key and a coarse MCP token share an oversized permission boundary, even though the token’s shorter lifetime limits how long that access lasts.

The three scope granularity levels and what each one costs

Server-wide scopes put simplicity ahead of fine distinctions. A pair such as mcp.read and mcp.write is quick to implement and easy for users to understand during consent. The cost is a broad blast radius. A compromised token or misdirected agent can invoke any tool in the permitted class, so the distinction between reading and writing becomes the principal authorization boundary.

Resource-action scopes set limits on access by resource type. Names such as todos.read and todos.write separate what a caller can do without a grant for each tool. This is a practical middle ground for servers of moderate complexity because the consent screen can remain coherent while permissions become more selective. Per-tool scopes offer a finer distinction. They become worthwhile when individual tools have meaningfully different privilege levels, including read-only, destructive, and publishing operations.

That precision imposes a consent cost of its own. A server with many tools and a separate scope for each can present users with more permissions than they will read carefully. Granularity then weakens the informed-consent premise it was intended to support. The choice depends on whether a finer boundary separates tools with different authority or gives each tool its own permission name for the same authority.

Diagram: Scope Granularity: Three Levels, Three Trade-offs. Visualizes: Illustrate the three scope granularity levels described in the article as a ranked spectrum from coarsest to finest, showing for each level: its example scope names, its key…

Scope-filtered tool listing as a first-class security and efficiency mechanism

Scopes can govern discovery as well as execution. Filtering tools/list by the caller’s scopes prevents the server from advertising capabilities that the caller cannot use. An unfiltered response instead gives an attacker a map of what a broader token could reach. The server still needs to enforce scopes on each call, even with some tools kept out of the listing.

The fabwaseem.com MCP server demonstrates this distinction in production. A token with posts:read exposes only four tools, while full access exposes twenty-two. Its authorization policy also distinguishes what a tool would do. A create_post or update_post call that would publish additionally requires posts:publish, so possession of the tool’s other permissions does not automatically authorize publication.

This narrower surface also reduces context-window consumption. An agent with limited scopes receives a smaller, coherent set of tools rather than descriptions of operations it cannot perform. That reduces the probability of the agent attempting an inaccessible operation while keeping unavailable capabilities out of its tool listing. Both benefits depend on how scopes are mapped to tools. Coarse scopes that expose the entire catalog to any authenticated caller leave little room for filtering.

Diagram: Scope Filtering Shrinks Attack Surface and Context Window. Visualizes: Show the concrete contrast from the fabwaseem.com MCP server: a token with 'posts:read' scope exposes only 4 tools in the tools/list response, while full access exposes…

A naming convention that scales across a fleet of MCP servers

The MCP specification does not prescribe scope names for individual tools. Implementations therefore range from broad names such as mcp:tools to resource-action names such as database.read. Names such as read:database, write:database, and admin:* are hard to compare when servers name related permissions in different ways.

The practical response is to establish a consistent resource-action convention before deploying a second server. Consistency gives auditors a stable vocabulary for comparing grants without treating the spelling itself as an authorization rule. Sentry’s self-hosted MCP deployment illustrates a non-trivial upstream mapping. Its required upstream scopes are org:read, project:read, project:write, team:read, team:write, and event:write. The resource-action pattern applies across resource types, while the distinction between MCP permissions and upstream permissions remains explicit.

Token passthrough, confused deputy, and the upstream scope boundary

An MCP client’s token is not an upstream credential. When an MCP server calls another service, it must act as an OAuth client to that service and obtain separate tokens. Passing through the token received from the MCP client creates a confused deputy vulnerability regardless of the quality of the MCP-layer scopes. The upstream API may honor a token without being able to verify the MCP server’s authority to act on it.

The June 2025 MCP specification explicitly prohibits token passthrough to upstream APIs, and that prohibition continues in the July 2026 specification. The MCP server holds its own upstream credentials, obtains access tokens scoped to the service’s requirements, and never exposes those credentials to the model or client. Sentry’s upstream scope mapping represents permissions held by the MCP server with Sentry. MCP-layer consent and upstream authority must therefore be mapped deliberately as distinct grants.

Step-up authorization and mid-task scope escalation

An agent may discover mid-task that an operation requires permissions absent from its initial token. Step-up authorization uses a challenge to ask for those extra scopes. The July 2026 revision added a scope-union requirement. Servers should name every scope a call needs in one challenge, and clients should request the union of scopes they already held and those in the new challenge.

Requesting only the new scopes can accidentally narrow access. The replacement token may lose permissions for tools the agent was already using, turning an escalation into a workflow failure. Scope design therefore needs plans for escalation paths as well as an initial consent screen. Knowing which tools require elevated permissions allows the initial grant to remain narrow while the step-up path is clear and tested.

Scope design in multi-tenant and per-user agent deployments

Per-user OAuth flows keep each user’s grants apart from the organization’s credentials that are shared across tenants. Each user authenticates to connected services with their own credentials, making access individually auditable and revocable without disrupting other tenants. Delegation needs its own boundary as well. Under the RFC 8693 Token Exchange pattern, the agent presents the human’s token as the subject and its own credential as the actor. The authorization server then mints a derived token with scopes narrower than the human’s original grant.

Access tokens should last one hour or less, and credentials should be issued per agent task so revoking a task’s grant terminates exactly that task’s access. Tool visibility should be filtered by tenant tier and scope, with audience and expiry validation enforced as well. Row-level data security keyed on tenant claims and per-tenant immutable audit logs with correlation IDs address boundaries beyond tool permissions. Persistent, isolated infrastructure gives each agent its own VM, disk, and credential store, while per-tenant secrets remain in a vault and credentials remain opaque to the model.

Token lifecycle management at fleet scale: refresh storms and the proactive refresh pattern

Reactive refresh can be appropriate for a single agent. At fleet scale, however, waiting for a 401 can concentrate refresh requests during agent bursts and trigger identity-provider rate limits. This thundering herd can break tools for many tenants at the same time. Agents may interpret these transient authentication failures as tool errors and abandon workflows, so the operational symptom becomes reduced task completion, obscuring the authentication outage.

The fleet pattern is to refresh shortly before expiry. Scheduling refreshes proactively spreads load across token lifetimes rather than concentrating requests at expiry boundaries. Scope breadth also determines how much a failed refresh disables. A token covering many scopes can take every tool behind those scopes out of service at once, while a narrower grant limits the failure to the tools it covers.

Authorization-server capabilities are another practical constraint on this design. Keycloak’s compliance matrix lists support for OAuth 2.1, RFC 8414 authorization server metadata, and RFC 9207 issuer identification. It marks RFC 8707 resource indicators as experimental. Because resource indicators provide the mechanism for binding tokens to a specific audience, that distinction is relevant when selecting an authorization server for MCP deployments.

OAuth handles authentication; it does not replace process isolation

A compromised or manipulated agent can still make a legitimate-looking call within its granted permissions, and a compromised tool can behave unexpectedly after accepting it. CVE-2025-54136 shows how this can happen through the rug-pull pattern. An MCP configuration entry’s command can be swapped after user approval, so the tool receiving the scoped token behaves differently from the one the user approved. OAuth scoping does not detect or prevent that change.

A Docker container with default settings and a Firecracker microVM represent different threat models and costs, with direct access to the host kernel a central distinction. A microVM-per-agent architecture gives each agent its own kernel, disk, and credential store, containing its ability to affect other agents or the host. Process isolation should be established first, then OAuth 2.1 scope design layered on top. Scopes constrain what a caller may request from the MCP server, while isolation contains what compromised execution can reach.

Sources

  1. Understanding Authorization in MCP - Model Context Protocol
  2. Authorization - Model Context Protocol

More in Agentic Protocol Internals