modelcontextprotocol / modelcontextprotocol/php-sdk
[Client] Implement refresh_token grant + offline_access scope
Nobody has claimed this yet.
- Dominant language
- PHP
- Stars
- 1.6k
- Forks
- 173
- Avg merge
- 2d 49m
- Merged PRs (30d)
- 23
Description
Context
When an access token expires, the client must transparently refresh using the stored refresh_token rather than re-prompting the user. Per OIDC/OAuth, offline_access scope is requested at authorize time when the AS advertises it; otherwise the client degrades gracefully (no refresh available).
Scope
Mcp\Client\Auth\Grant\RefreshTokenGrant.- Pre-flight check: if
expires_at - now() < skew, refresh before sending request. - Reactive: on
401with valid refresh token, refresh + retry once. - Request
offline_accessscope at authorize time whenscopes_supportedcontains it; otherwise omit. - If the AS does not advertise offline_access and tokens expire, surface a re-auth signal cleanly (no infinite loop).
Conformance scenarios unblocked
auth/offline-access-scope, auth/offline-access-not-supported.
Dependencies
Blocked by: #319 (need access+refresh tokens from auth code flow), #322 (scope handling).
Acceptance
- Unit tests for proactive + reactive refresh, no-refresh-token degradation, no-offline_access degradation.
- Conformance: 2 baseline scenarios pass.
cc @soyuka
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with Mcp\Client\Auth\Grant\RefreshTokenGrant and review dependencies #319 and #322 for the access/refresh token and scope-handling flow. Run the auth/offline-access-scope and auth/offline-access-not-supported conformance scenarios, then add the requested unit coverage for proactive and reactive refresh, degradation, and clean re-auth behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- authentication, authorization
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100