Skip to content

[Client] Implement OAuth scope handling (WWW-Authenticate, scopes_supported, step-up, retry-limit, omitted) #322

Description

@soyuka

Context

Five baseline scenarios cover scope acquisition strategies the client must follow when constructing authorize/token requests:

  • auth/scope-from-www-authenticate — parse scope="<list>" from WWW-Authenticate insufficient_scope challenges and request those scopes on next authorize.
  • auth/scope-from-scopes-supported — when no challenge hint, fall back to scopes_supported from AS metadata.
  • auth/scope-omitted-when-undefined — when neither source provides scopes, omit the scope parameter entirely (do not send empty string).
  • auth/scope-step-up — on 403/401 with error=insufficient_scope, restart auth flow requesting the augmented scope set.
  • auth/scope-retry-limit — bound step-up retries to one to prevent infinite loops.

Scope

  • Mcp\Client\Auth\ScopeResolver consulted by AuthCoordinator before every authorize/token request.
  • WwwAuthenticateParser returning scope, error, error_description, resource_metadata.
  • Step-up retry counter held in AuthCoordinator state.

Conformance scenarios unblocked

All 5 scope scenarios above.

Dependencies

Blocked by: #316 (401 plumbing), #318 (AS metadata), #319 (Auth Code flow).

Acceptance

  • Unit tests per resolution path.
  • Conformance: 5 baseline scenarios pass.

cc @soyuka

Activity

  1. added
    ClientIssues & PRs related to the Client component
    P1Significant bug affecting many users, highly requested feature
    authIssues and PRs related to Authentication / OAuth
    improves spec complianceImproves consistency with other SDKs such as TyepScript
    enhancementRequest for a new feature that's not currently supported
    on May 19, 2026
  2. chr-hertel commented on May 26, 2026

    @chr-hertel
    Member

    Cross-reference: the client-side accumulation portion of this work implements SEP-2350 for the MCP Spec 2026-07-28 release.

    Per RFC 6750 §3.1, servers report only scopes needed for the current operation in insufficient_scope 403 responses — clients are responsible for computing the union of (previously requested ∪ newly challenged) scopes when initiating step-up re-authorization. The client must track previously-requested scopes per AS (persist alongside tokens in #315).

    The matching server-side change is tracked as #362. See umbrella #338.

  3. removed
    P1Significant bug affecting many users, highly requested feature
    on Aug 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    ClientIssues & PRs related to the Client componentauthIssues and PRs related to Authentication / OAuthenhancementRequest for a new feature that's not currently supportedimproves spec complianceImproves consistency with other SDKs such as TyepScript

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions