In MCP, an HTTP 401 means the request needs authorization or the token is invalid, and a 403 with an insufficient_scope error means the token is valid but lacks scope for this operation. The client then runs a step-up flow to get a token with more scope, retries a few times at most, and treats repeated failure as permanent.
Definitions
Scope. A named permission inside an access token, such as files:read.
Step-up authorization. Asking for more scope later, when a privileged action is first attempted, instead of requesting everything up front.
WWW-Authenticate header. The response header where the server states what it needs: the metadata location, the error type and the scopes.
Status codes at a glance
| Code | Meaning in MCP | Client reaction |
|---|---|---|
| 400 | Malformed authorization request | Fix the request |
| 401 | Authorization required, or token invalid or expired | Discover the authorization server and get a token |
| 403 | Invalid scopes or insufficient permissions | Step up to the scopes in the challenge |
The flow
- The client calls the server with no token. The server returns 401 and a WWW-Authenticate header pointing to its resource metadata, optionally with a scope parameter.
- The client gets a token with the least scope it needs. The specification says to use the scope from the challenge if present.
- Later the model calls a tool that needs more. The server returns 403 with error insufficient_scope, the scopes needed, and the resource metadata URL.
- The client starts re-authorization for the new scope set. The specification recommends the server include both the existing relevant scopes and the new ones so the client does not lose what it had.
- The client retries the original request with the new token.
- If it still fails after a few attempts, the client stops. It should track upgrade attempts so it does not loop.
Clients acting for a user should attempt step-up. Clients acting on their own behalf may attempt it or abort.
Why this beats asking for everything
The security guidance warns about scope inflation. A token with wildcard or admin scopes granted up front turns a log leak into a full compromise, makes revocation disruptive and hides which operations a user actually intended. Progressive scopes limit the damage and make audit logs readable. The guidance suggests a small initial scope for low-risk discovery and read operations, with elevation logged using correlation IDs.
Server design checklist
- Publish only the scopes that make up basic functionality in scopes_supported.
- Return the precise scope in each challenge, not the whole catalog.
- Accept tokens with fewer scopes than requested.
- Log elevation events with the requested and granted subset.
- Do not use wildcards such as star or full-access.
Quick check
Should a server return 401 or 403 for a missing scope?
Use 403 with insufficient_scope when a valid token lacks scope. Use 401 when the token is missing, invalid or expired.
How many times should a client retry step-up?
The specification says a few times at most, then treat it as a permanent failure. Track attempts per resource and operation.
Does step-up replace human approval for risky tools?
No. It limits what a token can do. A confirmation prompt for sensitive operations is still a separate control the specification recommends for clients.
Where Safeguard fits
Safeguard provides policies, gates and guardrails for agent activity and agent identity, which helps you record which agent asked for which access. Run a free scan at gold.safeguard.sh/scan.
Sources
Last reviewed: 19 October 2026.
