Authorization changeddocs/2026-07-28/tools/inspector/authorization
Nearest release: v2.1.295, published 5 hours after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 8 Oct 2026 12:58 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 20 Oct 2026 20:07 UTC.
Upstream edited
Recorded here
Lines+58added
Lines−62removed
From line
6
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits4to this page, all time
The whole hunk
from line 6, old and new numbered
/
from line 6
66
77## The flow, end to end
88
9<Steps>
10 <Step title="Connect, and get refused">
11 The Inspector connects to the server URL. The server answers `401`. When the
12 response carries a `WWW-Authenticate` header, it points at the
13 protected-resource metadata URL (`resource_metadata`) and, optionally, the
14 scopes the request requires.
15 </Step>
9**1. Connect, and get refused**
1610
17 <Step title="Discover the authorization server">
18 The Inspector fetches the server's [protected-resource and
19 authorization-server
20 metadata](/specification/latest/basic/authorization/authorization-server-discovery)
21 to learn the endpoints and the supported grants.
22 </Step>
11The Inspector connects to the server URL. The server answers `401`. When the
12response carries a `WWW-Authenticate` header, it points at the
13protected-resource metadata URL (`resource_metadata`) and, optionally, the
14scopes the request requires.
2315
24 <Step title="Register or identify the client">
25 The Inspector identifies itself to the authorization server through
26 whichever mechanism is configured: [dynamic client
27 registration](/specification/latest/basic/authorization/client-registration#dynamic-client-registration),
28 a pre-registered static client (`--client-id` / `--client-secret`), a
29 [Client ID Metadata
30 Document](/specification/latest/basic/authorization/client-registration#client-id-metadata-documents)
31 (`--client-metadata-url`), or an [enterprise-managed
32 IdP](/extensions/auth/enterprise-managed-authorization).
33 </Step>
16**2. Discover the authorization server**
3417
35 <Step title="Authorize in the browser">
36 The Inspector opens the authorization URL. You sign in and consent.
37 </Step>
18The Inspector fetches the server's [protected-resource and
19authorization-server
20metadata](/specification/latest/basic/authorization/authorization-server-discovery)
21to learn the endpoints and the supported grants.
3822
39 <Step title="Receive the callback">
40 The authorization server redirects to the Inspector's callback URL, carrying
41 the authorization code.
42 </Step>
23**3. Register or identify the client**
4324
44 <Step title="Exchange and retry">
45 The code is exchanged for tokens, the tokens are persisted, and the original
46 connect is retried. For a [mid-session
47 challenge](#mid-session-re-authorization), the CLI retries the refused
48 request automatically, and the web client asks you to retry the action.
49 </Step>
50</Steps>
25The Inspector identifies itself to the authorization server through
26whichever mechanism is configured: [dynamic client
27registration](/specification/latest/basic/authorization/client-registration#dynamic-client-registration),
28a pre-registered static client (`--client-id` / `--client-secret`), a
29[Client ID Metadata
30Document](/specification/latest/basic/authorization/client-registration#client-id-metadata-documents)
31(`--client-metadata-url`), or an [enterprise-managed
32IdP](/extensions/auth/enterprise-managed-authorization).
5133
52<Frame caption="Connection Info after a completed OAuth flow: the authorization status, the dynamically registered client, and the granted scopes.">
53 <img src="https://mintcdn.com/mcp/gk28X8wi_tbRYzej/images/inspector/auth-connection-info.png?fit=max&auto=format&n=gk28X8wi_tbRYzej&q=85&s=01a8d11058c2d33e0069b8dec98591b5" width="3840" height="2160" data-path="images/inspector/auth-connection-info.png" />
54</Frame>
34**4. Authorize in the browser**
5535
36The Inspector opens the authorization URL. You sign in and consent.
37
38**5. Receive the callback**
39
40The authorization server redirects to the Inspector's callback URL, carrying
41the authorization code.
42
43**6. Exchange and retry**
44
45The code is exchanged for tokens, the tokens are persisted, and the original
46connect is retried. For a [mid-session
47challenge](#mid-session-re-authorization), the CLI retries the refused
48request automatically, and the web client asks you to retry the action.
49
50
51
5652## Callback URLs
5753
5854The web app listens for the OAuth callback on its own URL, while the CLI and TUI deliberately share a second one:
from line 63
6763
6864For the CLI and TUI, override it with `--callback-url` or `MCP_OAUTH_CALLBACK_URL`. The web callback always follows the page's origin, so `localhost` and `127.0.0.1` produce different redirect URIs there too.
6965
70<Warning>
71 The callback URL **must bind a loopback host**: `localhost`, `127.0.0.0/8`, or
72 `[::1]`. The listener receives the authorization code over plaintext `http`,
73 so a non-loopback host is rejected with an error and there is no flag to
74 override that. If your browser runs on a different machine, forward the
75 callback port to it, or complete the login in a web Inspector instead:
76 `--print-handoff` (below) prints a `portForwardCmd` for the web Inspector's
77 ports.
78</Warning>
66> [!WARNING]
67>
68> The callback URL **must bind a loopback host**: `localhost`, `127.0.0.0/8`, or
69> `[::1]`. The listener receives the authorization code over plaintext `http`,
70> so a non-loopback host is rejected with an error and there is no flag to
71> override that. If your browser runs on a different machine, forward the
72> callback port to it, or complete the login in a web Inspector instead:
73> `--print-handoff` (below) prints a `portForwardCmd` for the web Inspector's
74> ports.
7975
80<Note>
81 Redirect URIs must match your registration **exactly**. `http://localhost:6276/...` and `http://127.0.0.1:6276/...` are different URIs to an authorization server, even though they reach the same listener.
76> [!NOTE]
77>
78> Redirect URIs must match your registration **exactly**. `http://localhost:6276/...` and `http://127.0.0.1:6276/...` are different URIs to an authorization server, even though they reach the same listener.
79>
80> Only one process can hold the default port at a time; a second concurrent flow fails with `EADDRINUSE`. Use a different fixed port per instance, or `http://127.0.0.1:0/oauth/callback` for an OS-assigned ephemeral port when your authorization server supports dynamic redirect-URI registration.
8281
83 Only one process can hold the default port at a time; a second concurrent flow fails with `EADDRINUSE`. Use a different fixed port per instance, or `http://127.0.0.1:0/oauth/callback` for an OS-assigned ephemeral port when your authorization server supports dynamic redirect-URI registration.
84</Note>
85
8682## Where credentials live
8783
8884| File | Contents |
from line 143
147143
148144The `deepLink` in the handoff block navigates a browser straight to a *connected* Inspector; see [Deep links](/docs/2026-07-28/tools/inspector/web#deep-links).
149145
150<Note>
151 Because the stored entry records no expiry, a stored refresh token is
152 exercised on **every** `--use-stored-auth` run. With rotating (single-use)
153 refresh tokens that opens two narrow failure windows: two concurrent
154 invocations against the same state file can race for the token, and a crash
155 between a successful refresh and the write-back leaves the rotated token
156 unsaved. Both are unlikely; re-authorize in the web client to recover.
157</Note>
146> [!NOTE]
147>
148> Because the stored entry records no expiry, a stored refresh token is
149> exercised on **every** `--use-stored-auth` run. With rotating (single-use)
150> refresh tokens that opens two narrow failure windows: two concurrent
151> invocations against the same state file can race for the token, and a crash
152> between a successful refresh and the write-back leaves the rotated token
153> unsaved. Both are unlikely; re-authorize in the web client to recover.
158154
159155## Inspecting auth state
160156
No line in this hunk matches that.