Advertise scopes_supported separately from required_scopes #3778

Description

AuthSettings.required_scopes is used both to refuse tokens (RequireAuthMiddleware) and as scopes_supported in the protected resource metadata. So a server can't advertise a scope without requiring it on every request.

Our server's read tools need returns:read. One write tool also needs returns:write, which its handler checks with get_access_token(). We want read-only tokens to keep working, so we set required_scopes=["returns:read"]. But then the metadata lists only returns:read, and a client that takes its scopes from scopes_supported never asks for returns:write.

auth=AuthSettings(
    issuer_url=AnyHttpUrl("https://auth.example.com"),
    resource_server_url=AnyHttpUrl("http://127.0.0.1:8000/mcp"),
    required_scopes=["returns:read"],
)
# GET /.well-known/oauth-protected-resource/mcp
# -> "scopes_supported": ["returns:read"], with no way to also advertise "returns:write"

Proposal: an optional AuthSettings.scopes_supported, used for the metadata and defaulting to required_scopes. FastMCP's RemoteAuthProvider already separates these, and the TypeScript SDK's scoped-tools example advertises more scopes than it challenges for.

Our workaround is to insert our own route ahead of the SDK's at the same path. #3277 couples the challenge's scope to required_scopes in the same way.

Seen on mcp 2.3.0. I'm happy to open a PR if a maintainer assigns this.

This issue was written primarily by Claude Code. I hit this problem in our MCP server, and I've reviewed the issue.

References

• RFC 9728 §2 (scopes_supported): https://datatracker.ietf.org/doc/html/rfc9728#section-2
• FastMCP RemoteAuthProvider: https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/server/auth/auth.py
• TypeScript SDK example: https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/scoped-tools/server.ts
• Related: RequireAuthMiddleware omits RFC 6750 scope in WWW-Authenticate on 401/403 #3103, fix(auth): include RFC 6750 scope attribute in WWW-Authenticate challenges #3277