modelcontextprotocol/inspector

⚠️ This disables certificate verification for every TLS connection the Inspector process makes — every MCP server, every OAuth authorization server and token endpoint — not just the one you are testing, and Node prints a warning saying so. A connection that would have been refused for impersonation is then accepted. Never set it in a shell profile, a shared environment, or a deployment.

And 6278 if your app declares _meta.ui.domain. That is the spec field a server uses to ask its host for a stable, dedicated origin — without one the app runs at an opaque origin and its requests carry Origin: null, which no CORS / OAuth-callback / API-key allowlist can admit. The Inspector answers the request with a real loopback origin on a third listener, MCP_APP_ORIGIN_PORT (default 6278); apps that declare no domain never touch it. Publish it if you use one — this is the one failure that does not fall back: the backend publishes fine (its listener bound inside the container), so it hands t

⚠️ The flag is a no-op against a server that never challenges, so a green run is not evidence that your token store was seeded correctly. A smoke job whose server authenticates today and stops authenticating tomorrow — a misconfigured gateway, a route that silently became public — will keep passing. If you need to assert that authentication actually happened, assert it directly: run once without a usable token in an isolated MCP_STORAGE_DIR and require exit 3.

stdout is the result; stderr is diagnostics. Never merge them (2>&1) into something you then pipe to jq — the one place this guide does merge them is the secret scan in §7, which greps rather than parses.

Always bound the connect. --connect-timeout <ms> defaults to 15000 for ad-hoc --server-url/target runs and to the file-level timeout for --catalog/--config runs; 0 disables it. A CI job should never inherit a disabled timeout — a black-holed host would hang the runner until the job's own limit kills it.

The target is the LOWEST latest across a group — the version the whole group has reached — not the highest. npm publishes a lockstep release one package at a time, so a sweep landing mid-publish sees one package ahead of its three siblings. Targeting the highest would name a version three of them do not have and write a marker that suppresses the real filing once the publication completes, so the release would never be tracked at all. Taking the minimum keeps the issue actionable and lets the completed release file its own.

One version per install-crossing dependency. When bumping a dependency the shared sources pull in, bump it in every install that declares it. Consolidating to the root is what makes most of these unbumpable in two places at once, but it does not retire the rule — a client's devDependencies, and any package that arrives transitively into a client install, can still skew against the root. Never raise the tsc heap to work around one. npm run verify:dep-lockstep enforces this in two tiers: packages that reach one tsc program from two installs (the #1896 heap-exhaustion class), and — since #2226 —

⚠️ Deleting the declaration does not always delete the copy, and the local copy still wins. npm auto-installs an unmet peer into the install that needs it, and it has no visibility into the root's tree — so a client-only ESLint plugin drags a client-local eslint in (eslint-plugin-react-refresh/-storybook in web, eslint-plugin-react-hooks in tui), and web's Storybook/Vitest stack drags in a local typescript and vitest. A hoisted transitive does the same: @types/express puts an @types/node in web and cli. Those copies sit nearer than the root's and take precedence. The consolidation is therefore

A client declares only what that client alone consumes — its own UI stack, its bundler-inlined packages, its dev tooling. clients/cli and clients/launcher therefore declare no runtime dependencies at all, and that is the expected steady state, not an omission: everything they run on is root-declared and resolves by walk-up from the client directory. Re-adding a root-declared package to a client manifest re-creates the second copy this rule exists to make impossible (#1896), so a missing module at runtime is a signal to check the root manifest and the client's external list, never to add it bac

⚠️ Unset a variable rather than setting it to an empty string. The two are not interchangeable: HOST="" is read as an all-interfaces bind and refused, and an empty path variable such as MCP_STORAGE_DIR= or MCP_INSPECTOR_LOG_DIR= can resolve relative to the working directory instead of falling back to the default. A row says so explicitly where an empty value is treated as unset.

⚠️ Keep supplying the same passphrase on every run: a file that can no longer be decrypted is read as empty and refuses to be written. Everything else about the store — the selection order, the file's location, encryption, permissions, locking, and choosing a store explicitly with MCP_INSPECTOR_SECRET_STORE — applies to every runtime and is in Where secrets are stored.

[!WARNING] Mounting that volume turns on file storage of secrets, and without a key the file is plaintext. Every OAuth client secret, IdP client secret and stdio env: value you save is then written to secrets.json on the volume, readable by anyone who can read the volume: root and every member of the docker group on the host, and anyone who gets a backup, snapshot or copy of it. Mode 0600 only keeps out other non-root users. > Give it a key, and keep that key only where the Inspector can read it. Generate one into a file only you can read, outside the volume, backups and any repository tha

So the same volume that keeps your server list also switches secrets from session-scoped to durable — nothing extra to configure. The in-memory default for an unmounted container is deliberate: a file in the writable layer is discarded by --rm and by every image update, and promising durability it can't deliver is worse than declining to. The check looks at the directory that holds the secrets file, so if you relocate it with -e MCP_STORAGE_DIR=… or -e MCP_INSPECTOR_SECRET_FILE=…, mount a volume at that file's parent directory. Don't bind-mount the file on its own: it is not recognized as dura

⚠️ set -e does not fire for a command on the left of |; only the pipeline's last status is checked unless set -o pipefail is also on. Every example here pipes into jq, so keep pipefail.

⚠️ pipefail gives you a failure, not the CLI's failure. It reports the rightmost non-zero status, so when both sides fail the CLI's class is lost:

⚠️ Capture the status with || status=$?, not with if ! cmd; then status=$?. ! inverts the pipeline's status, so $? inside that branch is 0 and every failure class looks identical.

That coercion is the trap: a zip code, an order number, or an ID that happens to be all digits arrives at the server as a number through --tool-arg, and a schema expecting a string rejects it. Prefer --tool-args-json for anything typed — it says exactly what you mean. Then assert on the payload:

⚠️ Do not put the recovery in a || { … } group and stop there. The group's own status becomes the list's status, so a successful jq turns a failed run into a green one — the exact failure this guide warns about twice elsewhere. Capture into status, report, then exit with it.

⚠️ --app-info is a different shape, not a variation on this one. It probes without invoking the tool, so there is no result to report and the envelope is {"appInfo": …} alone. A consumer that requires .result will break on every --app-info run:

⚠️ If your stdio server takes flags of its own, you need a -- separator, and it splits the opposite way from the web and TUI clients. Under --cli, everything before -- is the target command and everything after is the Inspector's own options:

Please don't send a diff or open a pull request. Instead, open an issue that includes:

⚠️ vitest, @vitest/coverage-v8 and web's @vitest/browser-playwright are pinned exactly, and move together. @vitest/browser-playwright declares an exact peer on vitest, so it — not the root range — decides which vitest web installs. Left to float, the root resolves a newer patch and web's tests then run on one vitest while loading a coverage provider built against another. Bumping means editing all three in one change, the same discipline the exact prettier pin (#1790) exists for. ⚠️ Editing the three is necessary but not sufficient — clients/web also carries a vitest overrides entry that has t