Repository navigation
Description
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
Activity
Ben-Home commentedon Oct 29, 2026
dcnadler commentedon Nov 17, 2026
We would like the same split, but for a different use-case. When using Entra as IdP, no value of
required_scopesworks.Entra makes a client request the full scope name, e.g.
api://<app-id>/read. The token it issues has only the short name,read, in itsscpclaim. If a client requests bareread, Entra treats it as a Microsoft Graph scope.Testing on mcp 2.3.0:
required_scopes=["api://<app-id>/read"]: the metadata is right and sign-in works, butRequireAuthMiddlewarereturns 403 because the token's scopes sayread, notapi://<app-id>/read".required_scopes=["read"]: the scope check would pass, but clients requestreadand Entra refuses the sign-in.required_scopes=None: the metadata has no scopes, so the client sends noscopeparameter and Entra refuses.The proposed
AuthSettings.scopes_supported(as in #3783) would fix this. We would publish["api://<app-id>/read"], leaverequired_scopesempty, and check scopes and roles in our verifier.Other SDKs already keep the two lists apart. FastMCP's
RemoteAuthProviderhas separatescopes_supportedandchallenge_scopesparameters, documented for "Azure AD full URI scopes vs short-form" (see FastMCP 3002). The MCP spec allows the published and challenged scopes to differ.