You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 77846c2
Browse filesBrowse the repository at this point in the historyBrowse files
@@ -118,28 +125,40 @@ The per-request factory itself receives the same value as `ctx.authInfo`, so it
118
125
119
126
## Enforce per-tool scopes
120
127
121
-
`requiredScopes` gates the whole endpoint. For a scope only some tools need, check inside the handler — the handler is the only place that knows which tool is executing.
`requiredScopes` gates the whole endpoint. For scope step-up on an individual tool, set its `scopeChallenge` callback and configure `scopeChallenge.resourceMetadataUrl` on `createMcpHandler` (or a directly constructed Streamable HTTP transport). The callback receives the full parsed request and verified `authInfo`. Return `undefined` to continue, or return the exact, complete scope set to send `403 insufficient_scope` before invocation or SSE. Throwing or rejecting fails closed.
129
+
130
+
Use `requireScopes` for a static exact all-of check. Use a callback when the required scope set depends on the request:
A caller holding only `mcp` gets an ordinary tool result with `isError: true`, so the model reads the refusal and moves on instead of losing the connection.
133
-
134
-
::: info
135
-
Responding `403 insufficient_scope` at the HTTP layer instead triggers the client transport's automatic scope step-up (SEP-2350) — see [Authenticate a user with OAuth](../clients/oauth.md).
136
-
:::
155
+
Scope interpretation belongs to your callback; the SDK does not infer hierarchies, alternatives, or missing scopes. Challenged tools remain visible in `tools/list`.
137
156
138
157
## Recap
139
158
140
159
-`requireBearerAuth` from `@modelcontextprotocol/server` is the same gate for web-standard `fetch` hosts; the Express middleware adapts the same core.
141
160
-`requireBearerAuth` plus a `verifyAccessToken` you write turn an Express-mounted MCP route into an OAuth resource server; the SDK never issues tokens.
142
161
- Missing, invalid, or expired tokens get `401 invalid_token`; a token missing a `requiredScopes` entry gets `403 insufficient_scope`; both carry a `WWW-Authenticate: Bearer` challenge.
143
162
-`mcpAuthMetadataRouter` publishes the RFC 9728 document that challenge points at, plus a mirror of the AS metadata.
144
-
- Verified auth flows `req.auth` → `ctx.http.authInfo`; per-tool scopes are a check inside the handler that returns `isError: true`.
163
+
- Verified auth flows `req.auth` → `ctx.http.authInfo`; per-tool callbacks can trigger HTTP `403` scope step-up before invocation.
145
164
- The v1 Authorization Server helpers are frozen in `@modelcontextprotocol/server-legacy/auth`.
0 commit comments