Preamble

Status: Draft
Type: Standards Track
Created: 2025-11-23
Author(s): Kevin Gao

Abstract

This proposal formalizes Scope-Filtered Tool Discovery as an officially supported server behavior.

In this mode, an MCP server returns only the tools authorized for the scopes contained in the client’s current access token. Tools requiring scopes the client does not have are not included in tools/list.

This model aligns MCP with real-world OAuth semantics, where authorization influences not only what a client may execute but also which features it may see. This SEP standardizes this behavior to ensure interoperability and predictable behavior across MCP servers and clients.

This SEP does not require servers to filter tools; it simply codifies this mode as a legitimate and interoperable discovery strategy.

Nothing in MCP prevents this today — this SEP exists to remove ambiguity and standardize client expectations when servers choose this mode.

Motivation

MCP servers may expose large catalogs of tools with diverse privilege levels—some safe, some administrative, and some tenant- or policy-restricted. Because OAuth IdPs can dynamically adjust the scopes they grant (e.g., based on user role, policy, etc.), a client’s effective permissions may differ from what it originally requested.

Scope-filtered discovery allows the server to present a capability surface that accurately reflects the user’s actual authorization state. Servers can already return a subset of tools based on the current token, user, or policy. What is missing is a clear statement in the spec that this is an expected and valid discovery mode, and that clients must treat tools/list as non-exhaustive and entitlement-aware when authorization is used.

This SEP codifies behavior that is already needed in practice but not explicitly described in the current specification.

Specification

Definition

A server is operating in Scope-Filtered Tool Discovery Mode if:

1. tools/list returns only tools for which the current access token satisfies the tool’s authorization requirements.
2. Tools requiring missing scopes are omitted entirely from the response.
3. This filtering applies consistently to:
   • tools/list
   • any future tool-discovery endpoints

Determining Authorization

Filtering is applied based on:

• tool.authorization.scopes (from SEP-1880), if present
• Server-defined or internal authorization rules, if scopes are not declared

A tool may still fail at call time if additional dynamic or contextual checks fail.

Server Behavior

Servers implementing this filtering model:

• MAY use scopes, user roles, groups, or policy rules to determine which tools are visible
• MUST NOT expose metadata about filtered-out tools
• MUST return a stable filtered tool list for a given token
• SHOULD document that they operate in scope-filtered mode

Client Behavior

Clients interacting with MCP servers MUST treat the tool list as non-exhaustive:

• Missing tools MAY exist but be unauthorized for the current client
• Clients MUST handle tools appearing or disappearing after reauthorization
• Clients MUST respond normally to 403 insufficient_scope during execution and follow step-up authorization flows

Discovery Modes

MCP permits several options for server behaviors related to tool discovery:

Option 1 — Unauthenticated Discovery

All tools are visible without a token.

Option 2 — Baseline-Scope Discovery

Clients obtain minimal scopes via the initial 401 challenge, then see the server’s full tool catalog.

Option 3 — Scope-Filtered Discovery (This SEP)

Tool visibility reflects the scopes actually granted by the IdP.

This SEP does not require servers to use this option; it simply defines it as a standardized and interoperable mode.

Rationale

OAuth 2.0 explicitly allows authorization servers (IdPs) to return fewer or different scopes than the client requested. This behavior is fundamental to OAuth’s design and supported by the core specification:

As part of RFC 6749 §3.3: "The authorization server MAY fully or partially ignore the scope requested by the client, based on server policy or the resource owner’s instructions."

Because IdPs can and do adjust granted scopes based on policy or roles, clients cannot assume they will receive all the scopes they ask for. When a client receives a restricted scope set, the server must present a capability surface that accurately reflects what the IdP has authorized.

If servers were to always return all tools regardless of scopes:

• Privileged or sensitive operations would be discoverable by unauthorized users
• Agents would plan using tools that will always fail with 403 insufficient_scope
• Tenant- or subscription-restricted functionality would leak through discovery
• The server’s visible surface would diverge from the IdP’s binding permission decisions

Scope-filtered discovery prevents these issues by ensuring that the server’s tool list matches the user or agent's effective authorization.

Security Considerations

This does the following:

• Reduces exposure of privileged tool metadata
• Limits information leakage regarding tools
• Ensures capability visibility aligns with IdP-issued authorization

Backwards Compatibility

This SEP is fully backward compatible:

• Servers not using authorization are unaffected
• Servers may continue to use the current methods of tool discovery already part of the spec if desired
• Clients already must handle partial tool catalogs
• No existing fields or behaviors are removed

This SEP simply formalizes an already-allowed behavior to ensure predictable implementations.

Relationship to Other SEPs

SEP-1880 (Tool-Level Scopes)

Provides the metadata used to determine visibility under this model.

SEP-1821 (Dynamic Tool Search)

Search and filtering (e.g., SEP-1821’s query parameter) operate only on the scopes the client is already authorized for. This SEP clarifies that search MUST NOT be used to infer or reveal the existence of tools outside the authorized scope-visible surface.