Skip to content

Support the MCP step-up authorization flow for scope challenges - #478

Draft
jancurn wants to merge 3 commits into
mainfrom
claude/epic-goldberg-ohoe92
Draft

jancurn wants to merge 3 commits into
mainfrom
claude/epic-goldberg-ohoe92

Conversation

@jancurn

@jancurn jancurn commented Nov 4, 2026 •

Copy link
Copy Markdown
Member

A command the server answers with 403 insufficient_scope used to surface as a generic "Insufficient scope" server error with no way forward. mcpc now follows the MCP step-up authorization flow as far as a client that never opens a browser on its own can: the error names the missing scope and the exact login --scope "<current scopes plus the missing one>" to run, and the session stays usable.

  • 403 insufficient_scope fails with exit code 4 and a copy-paste login --scope ... plus restart hint; the session is not marked unauthorized.
  • login without --scope reads the server's 401 WWW-Authenticate challenge (first in the spec's scope selection order) and unions its scope with the profile's current scopes; --scope stays verbatim.
  • Client-credentials and id-jag sessions step up through the SDK; an e2e suite covers that and the static-header case against a new scope gate in both test servers.
  • The For details, run: ... logs hint moves to its own line for multi-line errors so it never sticks to the command.

Refs the review in this session (no issue filed).

🤖 Generated with Claude Code

https://claude.ai/code/session_015wgSmuAJRjQz56MXXBpFTF

A command the server answers with 403 insufficient_scope used to surface as a
generic "Insufficient scope" server error (exit 2) with no way forward. The
bridge now recognises the SDK's InsufficientScopeError, keeps the session live
(the token is valid, only a scope is missing) and fails with exit code 4,
naming the required scope and the exact `mcpc login <server> --scope "<current
scopes plus the missing one>"` to run, followed by `restart`. The logs hint
goes on its own line for multi-line errors so it never sticks to that command.

`login` without --scope now probes the server's 401 WWW-Authenticate challenge
(the first choice in the spec's scope selection strategy) and unions its scope
with the scopes the profile already holds, so a re-login never drops a
permission; the challenge's resource_metadata URL is handed to the SDK too.
With --scope, exactly those scopes are requested. The requested scope is
recorded on the profile when the token response omits `scope`.

Client-credentials and id-jag sessions already step up through the SDK; the
new e2e suite covers that path as well as the static-header case, against a
scope gate added to both test servers (SCOPE_GATE_TOOL / SCOPE_GATE_SCOPE).

Refs https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization#step-up-authorization-flow

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015wgSmuAJRjQz56MXXBpFTF
Keeps both the step-up authorization entries and the new `login --client-name`
entry in the changelog, and both constructor fields in OAuthProvider.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015wgSmuAJRjQz56MXXBpFTF
@jancurn jancurn changed the title Implement MCP step-up authorization (insufficient_scope) flow Support the MCP step-up authorization flow for scope challenges Nov 4, 2026
…rver

The scope probe `login` sends to read the server's 401 challenge ran before
the callback server was listening, so a server that stalls the probe delayed
the redirect port being bound (CI's `login --callback-port` test, which points
login at a hanging server, timed out after 10s). The probe now runs once the
callback server is up, and the requested scope is handed to the provider
through a setter instead of a constructor option.

Also keeps the step-up entries in a fresh [Unreleased] section above the
0.8.0 release that main cut, and both halves of the merged oauth-flow tests.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015wgSmuAJRjQz56MXXBpFTF

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants