Implement SEP-2207: OIDC-flavored refresh token guidance

[felixweinberger]

This is a tracking issue for implementation of SEP-2207.

[mattzcarey]

Status — SEP-2207 (OIDC-flavored refresh token guidance)

Track: C — independent, mostly already shipped.
Spec: seps/2207-oidc-refresh-token-guidance.md · merged

What's done

✅ #1523 merged 2026-03-30 (by @wdawson) into main. Live in packages/client/src/client/auth.ts:

• Appends offline_access to the requested scope when the AS advertises it AND the client metadata supports the refresh_token grant
• Uses the returned refresh_token for token refresh

Despite the misleading PR title/body mentioning "Python SDK", #1523 is a TS-SDK change (modifies packages/client/src/client/auth.ts, auth.test.ts, and test/conformance/src/everythingClient.ts).

Outstanding (acceptance criteria, summary)

• R-2207-2 (wire): Client SHOULD include refresh_token in grant_types client metadata when refresh tokens are desired — verify the DCR body actually emits this in the SDK's default clientMetadata
• R-2207-4 (wire): Server (PRM) SHOULD NOT include offline_access in WWW-Authenticate scope or PRM scopes_supported
• R-2207-3 (sdk): Client MUST NOT assume refresh tokens will be issued — token response lacking refresh_token despite advertising the grant → SDK proceeds without error; subsequent expiry triggers full re-auth, not refresh
• R-2207-1 (guidance): Refresh tokens kept confidential in transit and storage

What to verify / button up

1. Confirm SDK default clientMetadata.grant_types includes "refresh_token" (R-2207-2)
2. Add a test for "AS issues access token without refresh_token despite grant advertised" → next 401 triggers full re-auth, no exception
3. Confirm OAuthClientProvider.saveTokens is documented as needing secure storage (R-2207-1 — guidance, doc check)

Related work to consider

• Client should silently refresh access tokens on 401 when a refresh token is available #2031 (open issue, by @localden): "Client should silently refresh access tokens on 401 when a refresh token is available" — the operational complement to SEP-2207. Worth tracking on this issue or making it a sub-issue.
• #2702 (spec PR, open) — "SEP: MCP Client Silent Refresh on 401 Invalid Token" — related future spec work; not release-1.

Coordination

• Mostly done. Action is verification + small test additions.
• Bundleable with Implement SEP-837: Update authorization spec to clarify client type requirements #2198 (typing structuredContent indirectly causes type error #837) and Implement SEP-2350: Clarify client-side scope accumulation in step-up authorization #2200 (#2350) in an auth-release-1 clarifications PR series.