Skip to content

Commit d2f5183

Browse files
committed
[Doc] State the HTTP status of a require_scopes! failure on the modern path
## Motivation and Context The Authorization page said that a `require_scopes!` failure inside a handler leaves the HTTP status at 200. That holds on the legacy path and on a modern response streamed as SSE, but a modern response returned as JSON carries the status the transport gives every `-32600`, which is 400. The prose and the Response Reference row now say so. ## How Has This Been Tested? Documentation only. The mapping is `StreamableHTTPTransport#modern_http_status`, which answers 400 for the codes in `MODERN_BAD_REQUEST_CODES`, `-32600` among them, and the existing transport tests cover it. ## Breaking Changes None.
1 parent 4a9f7ad commit d2f5183

1 file changed

Lines changed: 4 additions & 2 deletions

File tree

‎docs/_server/authorization.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -282,8 +282,10 @@ and never cached on the MCP session, so token expiry takes effect mid-session; r
282282
which `IntrospectionVerifier` does on every request, while a locally validated JWT stays accepted until it expires.
283283

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

329331
## Client Side
330332

0 commit comments

Comments
 (0)