Handle an MCP insufficient_scope 403 and perform step-up authorization without losing previously granted scopes

Documented steps

1. Server side: when a request arrives with a valid token whose scopes are insufficient, respond HTTP 403 Forbidden (not 401) with WWW-Authenticate: Bearer error="insufficient_scope", scope="<required scopes>", resource_metadata="<PRM URL>", and optionally error_description.
2. Server side: include every scope required for the current operation in that single challenge, and account for scope hierarchies where a broader scope implies narrower ones when deciding sufficiency.
3. Client side: parse the error and the scope value from the WWW-Authenticate header.
4. Client side: compute the required scope set as the UNION of the scopes you previously requested and the scopes named in the current challenge — this is what preserves permissions needed for your other operations.
5. Client side: initiate re-authorization with that union scope set, running the full flow again including PKCE and the resource parameter.
6. Client side: retry the original request with the new token. A client acting on behalf of a user SHOULD attempt step-up; a client_credentials client acting on its own behalf MAY step up or abort immediately.
7. Client side: cap retries at a few attempts, track scope-upgrade attempts per resource-and-operation pair, and treat continued failure as a permanent authorization failure rather than looping.
8. Confirm the flow at https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/index