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 aa2a3fe
Browse filesBrowse the repository at this point in the historyBrowse files
Let tools declare alternative authorization paths, require all scope checks
within a path, choose paths from the request, and return an HTTP 403 scope
challenge before tool execution when the token is insufficient.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@@ -118,28 +125,46 @@ 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, declare `scopes` on the tool and pass `scopeChallenge.resourceMetadataUrl` to `createMcpHandler` (or a directly constructed Streamable HTTP transport). The SDK checks the verified `AuthInfo.scopes` before invocation and returns `403 insufficient_scope` without opening SSE.
129
+
130
+
`scopes: ['notes:read', 'notes:write']` is one execution path with exact `allOf` semantics. For alternatives, put named paths in the policy's `anyOf`. Each path has an `allOf`, and each entry accepts its canonical `challenge` scope or an exact alternative in `anyOf`.
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.
159
+
The selector receives the full parsed request and returns applicable path names. Declaration order determines which path is used for a challenge. The challenge keeps a held scope for each check already met and requests `challenge` for each unmet check. Return `undefined` for malformed or incomplete arguments so normal input validation handles them.
133
160
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
-
:::
161
+
Scope matching is exact. Keep provider-specific authorization checks in your token verifier or handler. Scoped tools remain visible in `tools/list`. Do not expose sensitive selector arguments through `x-mcp-header`.
137
162
138
163
## Recap
139
164
140
165
-`requireBearerAuth` from `@modelcontextprotocol/server` is the same gate for web-standard `fetch` hosts; the Express middleware adapts the same core.
141
166
-`requireBearerAuth` plus a `verifyAccessToken` you write turn an Express-mounted MCP route into an OAuth resource server; the SDK never issues tokens.
142
167
- 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
168
-`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`.
169
+
- Verified auth flows `req.auth` → `ctx.http.authInfo`; per-tool scope policies can trigger HTTP `403` step-up before invocation.
145
170
- The v1 Authorization Server helpers are frozen in `@modelcontextprotocol/server-legacy/auth`.
0 commit comments