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 c5a7ce9
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/_client/authorization.md
+16-11Lines changed: 16 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -47,9 +47,9 @@ pass an `MCP::Client::OAuth::Provider` to the transport instead of a static `Aut
47
47
- On a `403 Forbidden` whose `WWW-Authenticate` header carries `error="insufficient_scope"` (OAuth 2.0 step-up, RFC 6750 Section 3.1 and the MCP scope-selection-strategy),
48
48
run a fresh authorization request for the union of the currently granted scope and the scope named in the challenge, then retry the failed request once.
49
49
The refresh path is bypassed because refreshing would re-issue the same scope set the server just rejected. A `403` without that challenge is surfaced unchanged.
50
-
-By default, request`offline_access` when the client declares the `refresh_token` grant and the authorization server advertises it in
51
-
`scopes_supported` (SEP-2207). This can enable refresh tokens. The optional `scope_selector` below can remove it, while a selector
52
-
cannot reintroduce `offline_access`when the authorization server does not advertise it.
50
+
-Request`offline_access` when the client declares the `refresh_token` grant and the authorization server advertises it in
51
+
`scopes_supported` (SEP-2207). The PRM scope selector below runs before this augmentation and cannot disable it.
52
+
Unsupported `offline_access`is stripped from every scope source.
53
53
54
54
```ruby
55
55
require"mcp"
@@ -100,14 +100,19 @@ Optional keyword arguments:
100
100
-`pending_authorization_max_age`: Integer seconds a pending authorization stays redeemable, counted from the moment `run!` saves it, when `callback_handler`
101
101
is omitted. Defaults to 600.
102
102
-`scope`: Space-separated fallback scopes when neither a challenge nor PRM advertises scopes.
103
-
-`scope_selector`: Optional callable invoked after the SDK chooses scopes from the challenge, PRM, or `scope` fallback and augments
104
-
`offline_access`, but before request validation and client registration. It receives a read-only array of candidate scope tokens;
105
-
return an array of valid OAuth scope tokens to replace them, or `nil` / `[]` to omit the authorization URL's `scope` parameter.
106
-
The default (`nil`) keeps the MCP scope-selection strategy unchanged. A selector can narrow or add custom scopes, but cannot
107
-
reintroduce unsupported `offline_access`. Filtering a challenged scope may leave the current operation unauthorized.
108
-
Return `[]` to omit the client's `scope` parameter on the first request, even if PRM advertises scopes. The AS can still apply
109
-
default scopes or reject the request ([RFC 6749 §3.3](https://www.rfc-editor.org/rfc/rfc6749#section-3.3)); check the granted
110
-
scope before treating the connection as unscoped, and allow later challenged scopes when needed.
103
+
-`scope_selector`: Optional callable for narrowing Protected Resource Metadata (PRM) defaults in the authorization-code flow.
104
+
It is invoked only when no nonempty challenged scope was supplied and PRM supplies the default `scopes_supported` list,
105
+
before `offline_access` augmentation, request validation, and client registration. It receives a read-only array of PRM tokens
106
+
and must return an array containing a subset; custom scopes and `nil` results raise `ArgumentError`. Return `[]` to request
107
+
none of those PRM defaults. Challenged scopes, including the step-up union, and provider fallback bypass the selector;
108
+
use `authorization_request_validator` to accept or refuse challenged scopes. With no selector, default behavior is unchanged.
109
+
This hook does not control `offline_access` augmentation or alter authorization-endpoint query parameters. Returning `[]`
110
+
does not guarantee an omitted `scope` parameter: refresh policy can add `offline_access`, and a prefilled endpoint scope
111
+
survives when the flow has no scope of its own. The AS can also apply defaults or reject the request
112
+
([RFC 6749 §3.3](https://www.rfc-editor.org/rfc/rfc6749#section-3.3)); inspect the granted scopes.
113
+
For example, with PRM defaults `mcp:read mcp:write`, `scope_selector: ->(scopes) { scopes & ["mcp:read"] }` narrows the
114
+
default request to `mcp:read`; `scope_selector: ->(_scopes) { [] }` requests no PRM defaults. If the AS supports
115
+
`offline_access` and the client declares `refresh_token`, either request still includes `offline_access` afterward.
111
116
-`authorization_request_validator`: Callable invoked with an `MCP::Client::OAuth::AuthorizationRequest` before any authorization request is built.
112
117
Returning a falsy value abandons the flow with `Flow::AuthorizationRefusedError`. See [Reviewing the authorization request](#reviewing-the-authorization-request).
113
118
-`http_client_customizer`: Callable invoked with the Faraday connection the SDK builds for the OAuth flow's own requests, after its defaults and before its origin guard.
0 commit comments