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 8 Oct 2026 13:07 UTC.
Upstream edited
Recorded here
Lines+18added
Lines−14removed
From line
43
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits3to this page, all time
The whole hunk
from line 43, old and new numbered
/
from line 43
4343
4444 <Step title="Exchange and retry">
4545 The code is exchanged for tokens, the tokens are persisted, and the original
46 connect (or, for a [mid-session challenge](#mid-session-re-authorization),
47 the request that was refused) is retried automatically.
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.
4849 </Step>
4950</Steps>
5051
from line 59
5859
5960| Surface | Default callback | Why |
6061| - | - | - |
61| **Web** | `http://localhost:6274/oauth/callback` | The main app server already has an HTTP listener. |
62| **Web** | `<origin you opened the Inspector at>/oauth/callback`, by default `http://127.0.0.1:6274/oauth/callback` | The main app server already has an HTTP listener. Copy the exact value from the **Redirect URI** field in Server Settings. |
6263| **CLI** | `http://127.0.0.1:6276/oauth/callback` | A dedicated loopback listener, so it doesn't collide with a running web Inspector. |
6364| **TUI** | `http://127.0.0.1:6276/oauth/callback` | The same listener as the CLI. |
6465
6566**Register `http://127.0.0.1:6276/oauth/callback`** on any IdP that requires pre-registered redirect URIs before using the CLI or TUI. A predictable default is the point: you register once and reuse it.
6667
67Override with `--callback-url` or `MCP_OAUTH_CALLBACK_URL`.
68For 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.
6869
6970<Warning>
7071 The callback URL **must bind a loopback host**: `localhost`, `127.0.0.0/8`, or
from line 72
7172 `[::1]`. The listener receives the authorization code over plaintext `http`,
7273 so a non-loopback host is rejected with an error and there is no flag to
7374 override that. If your browser runs on a different machine, forward the
74 callback port to it; `--print-handoff` (below) prints a ready-made
75 `portForwardCmd`.
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.
7678</Warning>
7779
7880<Note>
from line 87
8587
8688| File | Contents |
8789| - | - |
88| `~/.mcp-inspector/storage/oauth.json` | Tokens and client information, keyed by canonicalized server URL. Written owner-only. |
90| `~/.mcp-inspector/storage/oauth.json` | Non-secret OAuth state (discovery metadata, PKCE verifiers, granted scope, public client ids), keyed by canonicalized server URL. Written owner-only. |
8991| `~/.mcp-inspector/storage/client.json` | Install-level client settings (client metadata URL, enterprise IdP). The same file the web client's **Client Settings** dialog writes. |
9092| The server's `oauth` block in the [catalog file](/docs/2026-07-28/tools/inspector/configuration#catalog-file-format) | Per-server client id/secret, scopes, the enterprise-managed flag, and the [step-up](#mid-session-re-authorization) policy. |
9193
9294The path to `oauth.json` is resolved in order: `MCP_INSPECTOR_OAUTH_STATE_PATH`, then `<MCP_STORAGE_DIR>/oauth.json` (see [Environment variables](/docs/2026-07-28/tools/inspector/configuration#environment-variables)), then the default above. All three clients resolve it the same way. Command-line `--client-id` / `--client-secret` / `--client-metadata-url` override `client.json`.
9395
96The secrets themselves (access and refresh tokens, client secrets, registration access tokens, and IdP session tokens) are not in `oauth.json`. They go to the [secret store](/docs/2026-07-28/tools/inspector/configuration#where-secrets-are-stored), which is the OS keychain when one is reachable. `MCP_INSPECTOR_PERSIST_TOKENS` limits which acquired tokens are kept: `all` (default), `access` (no refresh tokens), or `none` (re-authorize every run). See [Secret store variables](/docs/2026-07-28/tools/inspector/configuration#secret-store-variables).
97
9498## Mid-session re-authorization
9599
96100A server can refuse a *single* request mid-session with a `401` or a `403 insufficient_scope`, and the Inspector handles both without dropping the connection:
from line 102
98102* **Re-authorization**: the token expired or was revoked. The Inspector parses the `WWW-Authenticate` challenge and re-runs the flow, then retries the failed request.
99103* **Step-up**: the request needs scopes the current token doesn't carry. The Inspector re-authorizes for the union of the held and required scopes, so the new token covers everything the old one did plus the newly required scopes.
100104
101In the **web** client this surfaces as a re-authorization banner. In the **CLI** it prompts on stderr:
105In the **web** client, re-authorization shows a **Re-authentication required** banner, and step-up opens an **Additional permissions required** dialog listing the scopes, which you confirm with **Authorize**. Each server's **Insufficient-scope response** setting can turn step-up off so the `403` surfaces as an error instead. In the **CLI**, step-up prompts on stderr:
102106
103107```
104108Proceed with step-up authorization? [y/N]
from line 128
124128
125129| Flag | Behavior |
126130| - | - |
127| `--use-stored-auth` | Read the stored auth for `--server-url` and inject `Authorization: Bearer`. When a refresh token is stored, run the refresh grant first and inject the **fresh** token, persisting the rotation. Exits `3` (listing the stored server URLs) when nothing matches. |
128| `--wait-for-auth <sec>` | Poll the state file until a token for `--server-url` appears, then inject it. Times out at `<sec>` with exit `3`. Use after handing a login off to a human. |
131| `--use-stored-auth` | Read the stored auth for `--server-url` and inject `Authorization: Bearer`. When a refresh token is stored, run the refresh grant first and inject the **fresh** token, persisting the rotation. Exits `3` (`no_stored_token`, listing the stored server URLs) when nothing matches. |
132| `--wait-for-auth <sec>` | Poll the state file until a token for `--server-url` appears, then inject it. Times out at `<sec>` with exit `3` (`auth_wait_timeout`). Use after handing a login off to a human. |
129133| `--list-stored-auth` | Print `{ oauthStatePath, storedServerUrls }` and exit without connecting. |
130134| `--print-handoff` | Print a JSON block (`deepLink`, `portForwardCmd`, `oauthStatePath`, `apiToken`) for `--server-url` and exit; this is everything a remote script needs to drive the browser side. |
131| `--relogin` | Delete the stored OAuth for this server URL before connecting. HTTP/SSE only. |
135| `--relogin` | Delete the stored OAuth for this server URL before connecting, and revoke the grant at the authorization server (skip with `--no-revoke`). HTTP/SSE only. |
132136
133A typical remote-VM sequence:
137A typical remote-VM sequence. It assumes a web Inspector is running on the VM with a known `MCP_INSPECTOR_API_TOKEN`, and the same value is exported in the shell below; without it, the handoff's `deepLink` carries no `autoConnect` token and the web client rejects it.
134138
135139```bash theme={null}
136140# On the VM: print what the human needs in order to complete OAuth in their browser
from line 158
154158
155159## Inspecting auth state
156160
157* **Web**: the Connection Info panel shows discovery results, the registered client, granted scopes, and token state, and offers **Clear OAuth state** for the active server.
161* **Web**: the Connection Info panel shows the authorization status, the client registration type, the client ID, granted scopes, and the access token, and offers **Clear OAuth state and disconnect** for the active server. Clearing also revokes the grant unless the server's **Revoke tokens on clear** setting is off.
158162* **TUI**: the **Auth** tab (`a`) shows the same fields and clears state the same way.
159* **CLI**: `--list-stored-auth` shows what's on disk, and `--relogin` discards it and starts over.
163* **CLI**: `--list-stored-auth` shows what's on disk, and `--relogin` revokes and discards it and starts over.
160164
No line in this hunk matches that.