SEP-2207: OIDC-flavored refresh token guidance#2207
SEP-2207: OIDC-flavored refresh token guidance#2207wdawson wants to merge 10 commits intomodelcontextprotocol:mainfrom
Conversation
wdawson
changed the title
There was a problem hiding this comment.
In docs/specification/draft/basic/authorization.mdx (line 509):
- **MAY** add offline_access to scopes when the AS metadata contains it in scopes_supported
This is a bit vague on timing and mechanism - does the client add offline_access to the scope parameter in the authorization request? The token request? Both? Let's make this explicit, e.g.:
- **MAY** add `offline_access` to the `scope` parameter of the authorization request when the AS metadata contains it in `scopes_supported`
|
@wdawson also, the spec change also provides quite a bit of normative guidance to Authorization Servers, but in most real MCP deployments the AS is a third-party system (Auth0, Okta, Keycloak, Entra ID, etc.) that MCP implementers don't control. I am not sure to what degree we want to go in depth around AS behavior design here. The AS bullets are largely unactionable for the typical MCP developer. It might be worth framing these as "when building a custom Authorization Server for MCP" or acknowledging that these describe ideal AS behavior that existing providers may or may not follow. |
| `WWW-Authenticate` scope or Protected Resource Metadata `scopes_supported`, as refresh | ||
| tokens are not a resource requirement. | ||
|
|
||
| When building or selecting an Authorization Server for use in protecting MCP Servers, |
There was a problem hiding this comment.
@localden
The AS bullets are largely unactionable for the typical MCP developer. It might be worth framing these as "when building a custom Authorization Server for MCP" or acknowledging that these describe ideal AS behavior that existing providers may or may not follow.
I addressed your feedback here. I agree it's a bit odd to put this here, but didn't see this specific guidance mostly for the first bullet point in the OAuth 2.1 document and wanted to make sure it was covered somewhere. I may have missed it. @aaronpk might speak to it better, but I'm happy to remove this AS guidance section entirely if we think it's covered sufficiently in other specs.
5 participants
This PR introduces guidance for MCP implementations using OIDC-flavored Authorization Servers regarding refresh token issuance and handling of the
offline_accessscope.Motivation and Context
MCP builds on OAuth 2.1, which doesn't require special scopes for refresh tokens—the AS decides based on client capabilities. However, many OIDC Authorization Servers require the
offline_accessscope.This creates a gap: MCP clients interacting with OIDC-flavored servers may not receive refresh tokens, resulting in a poor UX (frequent re-authentication). This SEP clarifies:
offline_accessin their responsesDiscord discussion: MCP Authorization channel (Jan 2026)
How Has This Been Tested?
This is a specification/documentation change. The guidance has been reviewed by OAuth experts in the MCP community.
I plan to make appropriate changes to the MCP SDKs (at least TypeScript and Python, but will aim for Rust as well for Goose).
We also implemented this guidance for the Authorization Server and MCP server at Arcade.dev for MCP Gateways. You can sign up and create one for free to test with any MCP-compatible client.
Breaking Changes
None. This is additive guidance that does not change existing behavior.
Types of changes
Checklist
Additional context
Sponsor: @pcarleton
AI Disclosure: AI helped to create the structure of the SEP document. I reviewed and edited the text by hand afterward and manually contributed the specification change itself.