Can tools/list surface scope requirements to reduce runtime 403s?

[narensr]

Pre-submission Checklist

• I have verified this would not be more appropriate as a feature request in a specific repository
• I have searched existing discussions to avoid duplicates

Your Idea

Can tools/list surface scope requirements to reduce runtime 403s?

The MCP spec (2025-11-25) defines a solid step-up authorization flow in the Authorization section. But the flow is entirely reactive — the client only learns about missing scopes after a tools/call fails with 403 insufficient_scope. In enterprise deployments with 100+ tools, this creates a significant inefficiency.
I wanted to raise a question about whether the spec could enable clients to learn about scope requirements proactively during tools/list, rather than discovering them incrementally through 403s.

For context, here's what the authorization spec provides today — this is well-designed and I'm not questioning it:
Protected Resource Metadata (RFC 9728): The server publishes scopes_supported at the server level via /.well-known/oauth-protected-resource. This tells the client what scopes exist.
Scope Selection Strategy: On initial 401, the client reads the scope parameter from the WWW-Authenticate header, or falls back to scopes_supported from PRM. The spec says:

"This approach accommodates the general-purpose nature of MCP clients, which typically lack domain-specific knowledge to make informed decisions about individual scope selection."

Step-Up Authorization Flow (Section: Scope Challenge Handling):

When a tools/call fails with insufficient scopes, the server responds:
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope",
scope="files:read files:write user:profile",
resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
error_description="Additional file write permission required"
The client then parses the required scopes, re-authorizes, and retries. The spec also notes:

"The scopes_supported field is intended to represent the minimal set of scopes necessary for basic functionality, with additional scopes requested incrementally through the step-up authorization flow."

This is a clean, standards-compliant design. The question is whether it can be optimized for the tool discovery phase.

Question 1: Could tools/list include scope requirements per tool?
The Tool schema today includes annotations for behavioral hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint). These help clients and LLMs understand tool behavior before invocation.
Could there be an equivalent for authorization? For example:

json{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "read_incident",
        "description": "Read incident details",
        "inputSchema": { ... },
        "annotations": { "readOnlyHint": true },
        "requiredScopes": ["incident:read"]
      },
      {
        "name": "delete_incident",
        "description": "Delete an incident",
        "inputSchema": { ... },
        "annotations": { "destructiveHint": true },
        "requiredScopes": ["incident:delete"]
      },
      {
        "name": "escalate_incident",
        "description": "Escalate incident priority",
        "inputSchema": { ... },
        "requiredScopes": ["incident:escalate"],
        "requiredAuthLevel": "mfa"
      }
    ]
  }
}

Question 2: Should tools/list be user-scoped?

Related but distinct question: should tools/list return all tools or only tools the authenticated user/agent can invoke?

Today, the spec says:

To discover available tools, clients send a tools/list request.

There's no mention of whether the response should be filtered by the client/user authorization. The tools/list request has cursor for pagination but no authorization context.

Alice (scopes: incident:read, cmdb:read):
  tools/list → 150 tools (including 110 she can't use)

Bob (scopes: incident:*, cmdb:*, change:*, admin:*):
  tools/list → 150 tools (can use all of them)

This creates two problems:
For LLMs: 150 tools in the context window when the user can only use 40. The extra 110 are noise — they increase token cost, dilute tool selection quality, and increase the probability of the LLM selecting an unauthorized tool.
For the step-up flow: The spec's incremental step-up pattern assumes the client will hit a few scope boundaries during normal use. But if 70% of the tools are inaccessible, the client is hitting 403s constantly — the exception becomes the norm.

Scope

• Protocol Specification
• SDK Features
• Documentation
• Developer Experience
• Other

[Starlight143]

I strongly agree that discovering authorization requirements only after a 403 is too reactive for large enterprise tool surfaces.

My preference would be a two-layer model:

• discovery-time authorization hints in tools/list
• runtime challenge/error remains authoritative

In other words, tools/list should be able to say "this tool typically requires these scopes / approval classes / resource constraints", but the final decision should still happen at call time based on current token, current actor, current resource, and current environment.

That avoids over-promising at discovery time while still removing a lot of unnecessary trial-and-error.

I think something like this would be useful:

• required_scopes: [...]
• optional_scopes: [...]
• supports_step_up: true/false
• requires_approval: true/false
• resource_scoped: true/false
• authz_hint_version: "..."

I would also be careful about making tools/list fully user-scoped by default.

There’s value in separating:

1. tools that exist
2. tools visible to this caller
3. tools callable right now under current auth context

If those get collapsed into one response, clients lose useful planning information and operators lose debuggability.

So my vote would be:

• keep tools/list capable of exposing the broader tool surface
• add standardized authorization hints
• optionally support filtered/user-scoped views when a client explicitly asks for them

That seems like the best balance between discoverability, least privilege, and runtime correctness.