Recipes changeddocs/2026-07-28/tools/inspector/recipes
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 22 Oct 2026 20:37 UTC.
Upstream edited
Recorded here
Lines+19added
Lines−17removed
From line
31
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits5to this page, all time
The whole hunk
from line 31, old and new numbered
/
from line 31
3131 --header "X-Tenant: acme"
3232```
3333
34`--transport` accepts `http` (Streamable HTTP) and `sse`. If the server is protected, see [Authorization](/docs/2026-07-28/tools/inspector/authorization): no setup is needed in advance, because when the server answers `401` the Inspector runs the OAuth flow described there and retries the connection.
34`--transport` accepts `http` (Streamable HTTP) and `sse`. If the server is protected, see [Authorization](/docs/2026-07-28/tools/inspector/authorization.md): no setup is needed in advance, because when the server answers `401` the Inspector runs the OAuth flow described there and retries the connection.
3535
36For an HTTP server, also decide its [protocol era](/docs/2026-07-28/tools/inspector/protocol-eras). The default is `legacy`; set `modern` or `auto` in Server Settings (or `protocolEra` in the catalog file) to exercise the 2026-07-28 behavior. For an ad-hoc target, pass it at launch with `--protocol-era legacy|auto|modern`.
36For an HTTP server, also decide its [protocol era](/docs/2026-07-28/tools/inspector/protocol-eras.md). The default is `legacy`; set `modern` or `auto` in Server Settings (or `protocolEra` in the catalog file) to exercise the 2026-07-28 behavior. For an ad-hoc target, pass it at launch with `--protocol-era legacy|auto|modern`.
3737
3838## Importing an existing client config
3939
4040On the Servers screen, **Add Servers** can import MCP servers you have already configured
4141elsewhere instead of retyping them. It parses Claude Desktop, Cursor, Cline, and VS Code client
42configs directly, and it also reads a server's own [MCP Registry](/registry/about) `server.json`.
42configs directly, and it also reads a server's own [MCP Registry](/registry/about.md) `server.json`.
4343
44Import merges into the active [catalog](/docs/2026-07-28/tools/inspector/configuration#choosing-servers)
44Import merges into the active [catalog](/docs/2026-07-28/tools/inspector/configuration.md#choosing-servers)
4545(the Inspector's writable server list). When an imported server's id is already taken, you
4646choose whether to overwrite, skip or rename it. If you'd rather
4747not touch your catalog at all, launch against the foreign file read-only instead:
from line 54
5454
5555
5656
57Add Servers offers import from an existing client config or from a registry server.json.
58
5759## Reviewing an MCP App
5860
59[MCP Apps](/extensions/apps/overview) are tools that carry a UI widget. For an automated reviewer (CI or an agent), use the CLI for every check that returns JSON, and open a browser only to inspect the rendered widget.
61[MCP Apps](/extensions/apps/overview.md) are tools that carry a UI widget. For an automated reviewer (CI or an agent), use the CLI for every check that returns JSON, and open a browser only to inspect the rendered widget.
6062
6163**1. Probe the security posture without calling the tool**
6264
from line 109
107109http://127.0.0.1:6274/?serverUrl=<encoded url>&transport=http&autoConnect=<TOKEN>&openApp=<tool>&appArgs=<base64url(JSON)>&autoOpen=<TOKEN>
108110```
109111
110`appArgs` is the tool's arguments as base64url-encoded JSON, and every deep-link parameter is described under [Deep links](/docs/2026-07-28/tools/inspector/web#deep-links). `autoConnect` and `autoOpen` must both equal the session token, since `autoOpen` fires a tool call straight from the URL and needs the same gate as `autoConnect`.
112`appArgs` is the tool's arguments as base64url-encoded JSON, and every deep-link parameter is described under [Deep links](/docs/2026-07-28/tools/inspector/web.md#deep-links). `autoConnect` and `autoOpen` must both equal the session token, since `autoOpen` fires a tool call straight from the URL and needs the same gate as `autoConnect`.
111113
112114**5. Wait on a deterministic signal instead of sleeping**
113115
from line 129
127129docker run --rm -p 127.0.0.1:6274:6274 ghcr.io/modelcontextprotocol/inspector
128130```
129131
130Read the [session token](/docs/2026-07-28/tools/inspector/web#the-session-token) from the container logs, or pin it with `-e MCP_INSPECTOR_API_TOKEN=<value>`.
132Read the [session token](/docs/2026-07-28/tools/inspector/web.md#the-session-token) from the container logs, or pin it with `-e MCP_INSPECTOR_API_TOKEN=<value>`.
131133
132134The image defaults to `--web`, bound to `0.0.0.0:6274` with browser auto-open off, and runs as the non-root `node` user (uid `1000`). It sets `DANGEROUSLY_BIND_ALL_INTERFACES=true` because a container must bind the wildcard address to be reachable through `-p`.
133135
from line 140
138140> processes, and the page that discloses its token, on your local network. The
139141> image's `DANGEROUSLY_BIND_ALL_INTERFACES` covers the container's interfaces,
140142> not the host's. See [Publish the port on loopback
141> only](/docs/2026-07-28/tools/inspector/security#publish-the-port-on-loopback-only).
143> only](/docs/2026-07-28/tools/inspector/security.md#publish-the-port-on-loopback-only).
142144
143145To use the **Apps** tab, also publish the MCP Apps sandbox port, `6275`, and `6278` for an app that declares `_meta.ui.domain`. Publish each on the same port number inside and out, since the browser is handed the in-container port:
144146
from line 179
177179> (umask 077 && openssl rand -base64 32 > ~/.config/mcp-inspector/secret-key)
178180> ```
179181>
180> Even encrypted, secrets on disk carry moderate risk. See [what the file store protects against](/docs/2026-07-28/tools/inspector/security#what-the-file-store-protects-against).
182> Even encrypted, secrets on disk carry moderate risk. See [what the file store protects against](/docs/2026-07-28/tools/inspector/security.md#what-the-file-store-protects-against).
181183
182184Hand the key to the container **as a file** with `MCP_INSPECTOR_SECRET_KEY_FILE`, not as an environment variable. A key passed with `-e MCP_INSPECTOR_SECRET_KEY=…` is readable by anyone who can run `docker inspect` or `docker exec`.
183185
from line 213
211213
212214Without Swarm, Compose secrets are bind mounts that keep the host file's owner and mode, so the `0600` key file must be owned by uid `1000`. On a Linux host where your uid is different, run `sudo chown 1000 ~/.config/mcp-inspector/secret-key` rather than loosening its mode. Supply the **same** key on every run.
213215
214If the key file is missing, unreadable or empty, or both key variables are set, the Inspector **refuses to read or write the secrets file** rather than falling back to plaintext, and says why in the log and in the settings dialogs' footer. Everything else about the store (selection order, location, permissions) is under [Where secrets are stored](/docs/2026-07-28/tools/inspector/configuration#where-secrets-are-stored).
216If the key file is missing, unreadable or empty, or both key variables are set, the Inspector **refuses to read or write the secrets file** rather than falling back to plaintext, and says why in the log and in the settings dialogs' footer. Everything else about the store (selection order, location, permissions) is under [Where secrets are stored](/docs/2026-07-28/tools/inspector/configuration.md#where-secrets-are-stored).
215217
216218### Health checks and other modes
217219
218220The image's `HEALTHCHECK` probes the web UI at the address `HOST` binds. `--cli` and `--tui` have no web server, so the probe detects those modes from the container's arguments and reports healthy while they run. An external orchestrator (a Kubernetes probe, a Compose `healthcheck`) can call `GET /healthz` on the web port, which needs no token and returns only `{"status":"ok"}`.
219221
220`<target>` below is an [ad-hoc target](/docs/2026-07-28/tools/inspector/configuration#ad-hoc-targets): a positional stdio command, or `--server-url <url> --transport http`.
222`<target>` below is an [ad-hoc target](/docs/2026-07-28/tools/inspector/configuration.md#ad-hoc-targets): a positional stdio command, or `--server-url <url> --transport http`.
221223
222224```bash theme={null}
223225docker run --rm ghcr.io/modelcontextprotocol/inspector --cli <target> --method tools/list
from line 261
259261* **Behind TLS or a reverse proxy, give MCP Apps their public addresses.** By default the sandbox is advertised as `http://<bind host>:6275`, which an `https://` page blocks as mixed content. Set `MCP_SANDBOX_FULL_ADDRESS` (for example `https://inspector-sandbox.example.com/sandbox`) and, for apps that declare `_meta.ui.domain`, `MCP_APP_ORIGIN_FULL_ADDRESS` (for example `https://inspector-apps.example.com`). Each needs its own hostname or port; an address that shares the Inspector's origin is refused.
260262* **MCP Apps can't render at a bare IPv6 literal.** A bracketed IPv6 literal isn't a valid CSP host-source, so browse at a name or an IPv4 address.
261263
262Whatever the shape: keep authentication on. Do not set `DANGEROUSLY_OMIT_AUTH` on anything reachable by anyone but you. The reasoning is under [Security](/docs/2026-07-28/tools/inspector/security#the-web-backend-and-its-api-token).
264Whatever the shape: keep authentication on. Do not set `DANGEROUSLY_OMIT_AUTH` on anything reachable by anyone but you. The reasoning is under [Security](/docs/2026-07-28/tools/inspector/security.md#the-web-backend-and-its-api-token).
263265
264266## Keeping a connection open with mcpdo
265267
266When an exploration spans many calls (a multi-step flow over one session, a log you watch, an agent using a server's tools mid-session), reconnecting for every `--cli` invocation gets in the way. [mcpdo](/docs/2026-07-28/tools/inspector/mcpdo) holds the connection for you:
268When an exploration spans many calls (a multi-step flow over one session, a log you watch, an agent using a server's tools mid-session), reconnecting for every `--cli` invocation gets in the way. [mcpdo](/docs/2026-07-28/tools/inspector/mcpdo.md) holds the connection for you:
267269
268270```bash theme={null}
269271mcpdo connect my-server
from line 277
275277
276278A connection runs one call at a time, so commands against the same connection from other shells wait their turn.
277279
278The daemon that holds the connection starts automatically and exits about a minute after the last connection closes. Read [The mcpdo connection daemon](/docs/2026-07-28/tools/inspector/security#the-mcpdo-connection-daemon) before using it on a shared machine.
280The daemon that holds the connection starts automatically and exits about a minute after the last connection closes. Read [The mcpdo connection daemon](/docs/2026-07-28/tools/inspector/security.md#the-mcpdo-connection-daemon) before using it on a shared machine.
279281
280282## Development workflow
281283
from line 305
303305Turn what you found into a CI assertion: pipe the CLI's `--format json`
304306output to `jq -e` with `--stored-auth-only`, so a missing token fails fast
305307instead of starting interactive OAuth. See [Verify a server in
306CI](/docs/2026-07-28/tools/inspector/cli#verify-a-server-in-ci) for the full
308CI](/docs/2026-07-28/tools/inspector/cli.md#verify-a-server-in-ci) for the full
307309command.
308310
No line in this hunk matches that.