SEP-2207: OIDC-flavored refresh token guidance#2207
SEP-2207: OIDC-flavored refresh token guidance#2207mcp-commander[bot] merged 18 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. |
github-actions
bot
dismissed
their stale review
New commits pushed — approval invalidated.
|
New commits were pushed — removed the |
|
@kurtisvg, my bad. I just merged main here, trying to clear the failing status check earlier, and it looks like that canceled your approval |
|
/lgtm |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
/lgtm |
![mcp-commander[bot]](https://avatars.githubusercontent.com/in/3196832?s=60&v=4){kind=small}
|
@wdawson @nbarbettini looks like I can't resolve the conflict because I do not have permissions to the fork. Do you mind resolving the conflicts and pushing the changes so we can merge this? |
Head branch was pushed to by a user without write access
wdawson
dismissed stale reviews from mcp-commander[bot] and github-actions[bot]
via
a33e37b
mcp-commander
bot
removed
the
accepted
|
New commits were pushed — removed the |
|
/lgtm |
mcp-commander
bot
added
the
accepted
6 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.
SDK updates:
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.