Skip to content

[Doc] State the HTTP status of a require_scopes! failure on the modern path #597

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
koic merged 1 commit into from
Oct 13, 2026
+4 −2
Merged

[Doc] State the HTTP status of a require_scopes! failure on the modern path #597

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions docs/_server/authorization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -282,8 +282,10 @@ and never cached on the MCP session, so token expiry takes effect mid-session; r
which `IntrospectionVerifier` does on every request, while a locally validated JWT stays accepted until it expires.

`require_scopes!` raises `MCP::Server::OAuth::InsufficientScopeError`, which the server turns into a JSON-RPC invalid-request error (`-32600`)
whose `data` names the missing scopes; the HTTP status stays 200 and no `WWW-Authenticate` challenge is sent,
whose `data` names the missing scopes, and no `WWW-Authenticate` challenge is sent,
because step-up challenges (403 `insufficient_scope`) are the job of the transport-level `required_scopes:` gate.
The HTTP status is the one the transport gives every `-32600`: 200 on the legacy path and on a modern response streamed as SSE,
400 on a modern response returned as JSON.
The Python and TypeScript SDKs split endpoint-level challenges from in-handler authorization the same way.
Without bearer authentication `auth_info` is `nil` and `require_scopes!` fails closed.
Use it where one operation needs more than the endpoint as a whole:
Expand Down Expand Up @@ -324,7 +326,7 @@ and `scope` when `required_scopes:` is set or the metadata document advertises `
| `Bearer` header not carrying exactly one token | 400 `error="invalid_request"` |
| Valid token used against a session initialized by another principal | 404 as for an unknown session |
| Verifier raised anything outside the `OAuth::Error` hierarchy (JWKS or introspection endpoint down) | 500 without a challenge, reported through the exception reporter |
| `require_scopes!` failure inside a handler | JSON-RPC `-32600` in the normal 200 response, no HTTP challenge |
| `require_scopes!` failure inside a handler | JSON-RPC `-32600`, no HTTP challenge; 200 on the legacy path, 400 on a modern JSON response |

## Client Side

Expand Down
Loading