Implement SEP-2350: Clarify client-side scope accumulation in step-up authorization

[felixweinberger]

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

[mattzcarey]

Status — SEP-2350 (Client-side scope accumulation in step-up authorization)

Track: C — independent, starts now. Server-side reference impl already in active review.
Spec: seps/2350-clarify-scope-accumulation.md · merged

What's done

• main already has some WWW-Authenticate parsing and resolved-scope handling (via the OAuth provider adapter refactor) — see packages/client/src/client/auth.ts:581-595, 869+ and the packages/client/CHANGELOG.md entries.
• feat(server): OAuth scope challenge support (step-up auth) #1624 (open, by @SamMorrowDrums) — feat(server): OAuth scope challenge support (step-up auth):
  • Servers declare required OAuth scopes per tool
  • Transport checks authInfo.scopes before running the tool; if insufficient, returns HTTP 403 + WWW-Authenticate: Bearer error="insufficient_scope", ... to trigger client step-up
  • Initially used server-side accumulation (union of activeScopes ∪ required). After review by @localden cross-checking with the merged SEP-2350, this was changed in 2026-05-26 to:
    • Default WWW-Authenticate carries per-operation required scopes only (RFC 6750 §3.1, matches SEP-2350)
    • Opt-in additive mode via scopeChallenge.includeGrantedScopes: true for servers that need to be defensive against non-accumulating clients (e.g. GitHub MCP server style until VS Code does client-side accumulation)
• feat(server): scope challenges for resources, prompts, completions (stacked on #1624) #2157 (open, stacked on feat(server): OAuth scope challenge support (step-up auth) #1624) — extends scope-challenge to resources/read, prompts/get, completion/complete

Outstanding (acceptance criteria, summary)

• R-2350-1 (wire): Client SHOULD include challenged scopes alongside previously-granted scopes when re-authorizing (the client-side accumulation the SEP is named after)
• R-2350-2 (wire): Server SHOULD include scopes needed for current operation in scope param of WWW-Authenticate (RFC 6750 §3.1) — done in feat(server): OAuth scope challenge support (step-up auth) #1624 post-review
• R-2350-3 (wire): Server SHOULD include all required scopes in a single challenge (no incremental challenging) — done in feat(server): OAuth scope challenge support (step-up auth) #1624
• R-2350-4 (sdk): Client helper computing union of previously-requested + newly-challenged scopes for re-auth — not yet in main; this is the client-side complement of feat(server): OAuth scope challenge support (step-up auth) #1624 and the missing piece for R-2350-1
• R-2350-5 (guidance): Pre-existing — server SHOULD strive for consistency in scope-set construction; UX impact

Action items

1. Land feat(server): OAuth scope challenge support (step-up auth) #1624 (server-side reference, now SEP-2350-aligned)
2. Land feat(server): scope challenges for resources, prompts, completions (stacked on #1624) #2157 (extends to other primitives)
3. Open a client-side accumulation PR: a scope-set helper (mergeScopes(prior, challenged) → union) wired into the auth() re-auth flow. Referenced as related issue fix: accumulate OAuth scopes on 401/403 instead of overwriting #1657 in the feat(server): OAuth scope challenge support (step-up auth) #1624 discussion.

Coordination

• Server PRs ready to merge after rebase. Client work is independent and small.
• Bundleable with Implement SEP-837: Update authorization spec to clarify client type requirements #2198 (typing structuredContent indirectly causes type error #837) and Implement SEP-2207: OIDC-flavored refresh token guidance #2199 (fix: replay request SSE responses after disconnect #2207) in an auth-release-1 series.