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): add request-time OAuth scope challenges #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): add request-time OAuth scope challenges #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): add request-time OAuth scope challenges #1624 post-review
• R-2350-3 (wire): Server SHOULD include all required scopes in a single challenge (no incremental challenging) — done in feat(server): add request-time OAuth scope challenges #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): add request-time OAuth scope challenges #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): add request-time OAuth scope challenges #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): add request-time OAuth scope challenges #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.

[SamMorrowDrums]

@mattzcarey LMK if you want me to do anything to help land this? I'd love this to server as canonical example for other SDKs for how to handle scope challenges server side (that's the main goal of the #auth-wg-tool-scopes currently). I'd be happy to chat about things too if it's helpful to getting this over the line.

[norika1207-lab]

This looks worth pinning down as a protocol-level regression rather than only an implementation bug.

For client-side scope accumulation in step-up authorization, the acceptance test I would want is a minimal client/server fixture that records the exact JSON-RPC or HTTP exchange, then asserts both the wire result and the local lifecycle state after the failure path. In MCP deployments, the dangerous failures are often not just wrong return values; they are pending requests, dropped notifications, mismatched session state, or errors that get translated into a generic response and become impossible to diagnose.

A useful fix boundary would preserve three signals: the protocol error sent to the peer, the local exception or cancellation reason available to application code, and a trace/log field that ties the two together. That makes the behavior debuggable for agent hosts without requiring every host to special-case this SDK detail.