Proposal: Client-side Scope-Based Tool Filtering

[ouvreboite]

Proposal: Client-side Scope-Based Tool Filtering

TL;DR

Add an optional oauthScope MCP tool's annotation so MCP clients can filter out tools based on OAuth JWT scopes. This prevents LLMs from seeing tools they can't use, reduces failed API calls, and improves security without breaking existing implementations.
Additionally, this could allow clients to request permission "per-scope" during user interactions.

Example of tool definition with a required scope:

{
  "name": "deleteProject",
  "description": "Delete a project by its ID",
  "inputSchema": {
    "type": "object",
    "properties": {
      "projectId": {
        "type": "string"
      }
    },
    "required": ["projectId"],
  },
  "annotations": {
    "oauthScope": "project:manage" 🆕
  }
}

Summary

This proposal introduces a scope-based filtering mechanism for MCP tools that leverages existing OAuth 2.0 and JWT standards to prevent unauthorized tool exposure and reduce wasted API calls.

Problem Statement

Currently, MCP servers expose all available tools to clients regardless of the client's actual permissions. This leads to wasted tokens (tools being unnecessarily listed and called) and a poor user experience, as non-permitted tools can be called.
Additionally, a lot of client requires the users to validate each tool use (possibly allowing to validate a given tool for a session/workspace). This means that related tools, with a similar level of access still requires different validations by the users, which can be cumbersome.

Proposed Solution

Introduce a optional oauthScope tool annotation that allows MCP servers to specify OAuth scopes required for tool access. MCP clients would filter tools based on the current JWT token's scope claims before exposing them to the LLM.
When request user validation, clients could also allow the user to validate any tool with an identic scope.

Related RFC:

1. https://datatracker.ietf.org/doc/html/rfc6749
2. https://datatracker.ietf.org/doc/html/rfc9068

⚠️ The server should still be responsible to ensure a tool being called can be.

Handling AND/OR logic

Defining a single scope for a tool may not be enough. Some tools may requires several scopes ("AND") or instead allow access for different scopes ("OR"). For example OpenAPI supports an AND/OR syntax based on double nested arrays, which seems cumbersome.

Instead we can reuse the anyOf / allOf syntax already present in JSONSchema:

Example of a tool requires read AND write scope

{
  "name": "fooBar",
  "annotations": {
    "oauthScope": {
      "allOf": ["read","manage"]
    }
  }
}

Example of a tool requires read OR write scope

{
  "name": "fooBar",
  "annotations": {
    "oauthScope": {
      "anyOf": ["read","manage"]
    }
  }
}

[yannj-fr]

Totally agree on the usage, actually this is part of my current concern, how in an entreprise have a MCP catalog that will be role-based, both for users but also agents

[evalstate]

Hi -- just wanted to highlight that there has been ongoing community discussions on this topic (search-tools-wg) on the Community discord, and a related Pull Request with some discussion here: #322.

I'd recommend reviewing/joining the existing discussions https://modelcontextprotocol-community.github.io/working-groups/.

[ImanHeshmat]

Hi

I ran into the same behaviour and I think a server-side solution is the safest and most practical fix.

what I implemented was:

• Defining required_scopes on each tool (for runtime enforcement).
• Adding those scopes into the tool’s metadata.
• Writing a small middleware that intercepts ListToolsRequest and filters out tools if the client’s token scopes (from the built-in JWTVerifier) don’t match what the tool requires.

That way the client only sees the tools they’re actually authorized to use, which feels more secure and cleaner.

Hope that helps!