docs: new modelcontextprotocol.io Inspector documentation for v2 (legacy vs. modern era, more screenshots)

[cliffhall]

Summary

Write new, substantially expanded documentation for the MCP Inspector to replace the current page at https://modelcontextprotocol.io/docs/tools/inspector.

That page lives in a different repo (the modelcontextprotocol/docs site, not this one), but the work is tracked here on the v2 board because the content is entirely about the new (v2) Inspector and needs to be written by whoever knows it.

Why

The existing docs page predates v2 entirely. It documents the legacy single-surface web Inspector, has few screenshots, and says nothing about the things that most need explaining now: the three clients (Web / CLI / TUI) behind one mcp-inspector bin, and the fact that a connection is era-aware — the UI and the wire traffic differ meaningfully between a legacy-era server and a modern (2026-07-28) server.

Scope

New docs, based on the v2 Inspector, more detailed than today's page, with far more screenshots.

• Getting started — npx @modelcontextprotocol/inspector, the three surfaces (--web default, --cli, --tui), auth token, config/catalog files.
• Legacy vs. modern era operation — the core new theme. What Protocol Era (auto / legacy / modern) means, how negotiation works, and how each tab changes across the fork:
  • Logging: session-scoped logging/setLevel vs. per-request _meta log-level opt-in
  • Resource subscriptions: resources/subscribe vs. subscriptions/listen + stream-status badge
  • Tasks: capabilities.tasks + tasks/list/tasks/result vs. the io.modelcontextprotocol/tasks extension (SEP-2663), inlined results, tasks/update
  • Tools: SEP-2243 x-mcp-header mirrored params and excluded tools; the new -32602 error panels
  • Network/Protocol: standardized Mcp-* headers and the new error taxonomy (SEP-2243 / SEP-2575)
  • MRTR (input_required round-trips) and the pending-request modal
• Screenshots throughout — every tab, in both eras where they differ.
• Launcher flags, and the launcher/client split — the shared mcp-inspector launcher owns a deliberately tiny surface, and the docs should make that boundary explicit, because it's the thing --help explains least well. Verified against clients/launcher/src/:
  • Launcher-level flags — only these two:
    • --web (default) / --cli / --tui. At most one; specifying two errors (Specify at most one of --web, --cli, or --tui.). They are read only from a contiguous prefix of the user args — the first non-mode token ends parsing and everything after it is forwarded to the client unchanged, which is what lets a literal --cli appear later as a server's own argument.
    • -h / --help. Bare (no mode flag) prints the launcher's own help and exits; with a mode flag it is forwarded, so mcp-inspector --cli --help prints the CLI's help. Worth documenting explicitly — it's a real behavioral fork.
  • Everything else belongs to a client, and the docs should present the flag reference that way rather than as one flat list:
    • --dev (Vite dev mode) is web-only (clients/web/server/run-web.ts).
    • --catalog / --config / --server / --transport / --server-url / --cwd / -e / --header are defined separately by each of web, cli, and tui, so note where they diverge (e.g. cli/tui also take a positional [target...] for an ad-hoc server; web does not take OAuth client flags).
    • The OAuth flags — --client-id, --client-secret, --client-metadata-url, --client-config, --callback-url (must be loopback) — are cli + tui.
    • The large scripting surface — --method, --tool-name, --tool-arg / --tool-args-json, --uri, --prompt-name / --prompt-args, --log-level, --metadata / --tool-metadata, --app-info, --connect-timeout, --format, --use-stored-auth, --stored-auth-only, --relogin, --wait-for-auth, --list-stored-auth, --print-handoff — is cli-only.
  • --catalog vs. --config deserves its own explainer: --catalog is the writable catalog (created/seeded if missing; default ~/.mcp-inspector/mcp.json), --config is a read-only session file (served as-is, never written, errors if absent), and the two are mutually exclusive — enforced centrally in core/mcp/node/config.ts, so all three clients reject the combination identically.
  • The -- separator. web and cli split argv at a bare -- and pass the remainder through as the target command's own args. Document it — it's how you pass flags that would otherwise be eaten by the Inspector.
  • Environment variables, attributed to the right layer (none of these are launcher flags): MCP_DEBUG / DEBUG are read by the launcher (and duplicated in the TUI bin) to append a stack trace on a top-level failure — and only when meaningfully set, so DEBUG=0 / false / empty read as off. MCP_CATALOG_PATH, MCP_CLIENT_CONFIG_PATH, and MCP_OAUTH_CALLBACK_URL are the env fallbacks for the corresponding cli/tui flags. MCP_INSPECTOR_API_TOKEN, DANGEROUSLY_OMIT_AUTH, HOST / CLIENT_PORT, DANGEROUSLY_BIND_ALL_INTERFACES, and ALLOWED_ORIGINS are web-backend config, not launcher config.
• Per-surface guides — Web tabs walkthrough; CLI command/flag reference and scripting/CI recipes; TUI navigation.
• OAuth — the auth flow end to end, mid-session re-authorization, and the CLI/TUI loopback callback flow.
• Practical guides — connecting stdio vs. HTTP servers, importing existing client configs, MCP Apps review, Docker, host binding / origin allow-list.

The repo already has good raw material to draw on and link from: the root README.md, the per-client READMEs, docs/mcp-app-review.md, and the test-servers/configs/*.json showcase configs (each is a ready-made reproduction recipe for the era-fork behavior above).

Deliverable

A PR against the docs-site repo replacing/expanding docs/tools/inspector. This issue tracks the writing and review; link the docs-site PR here when it opens.

[cliffhall]

Draft written — prose complete, screenshots outstanding

First pass of the new docs is drafted on branch docs/inspector-v2 in a local checkout of modelcontextprotocol/modelcontextprotocol. Not pushed yet — see "Before the PR opens" below.

Structure

docs/tools/inspector keeps its URL as the overview page, and the new material sits in a folder nested under it in the Developer tools navigation group (same pattern the site already uses for Clients under Develop with MCP). No redirect needed, no URL churn on the page people already link to.

Page	Covers
docs/tools/inspector	Overview, the three surfaces, quickstart, the launcher/client boundary (the two launcher flags, prefix-only mode parsing, the bare-vs-mode --help fork).
docs/tools/inspector/protocol-eras	The centerpiece. The era setting (legacy default, auto, modern), why the default is not auto, client-side negotiation — then the fork feature by feature: logging, resource subscriptions, tasks, MRTR, x-mcp-header mirrored params + excluded tools + the -32602 panels, Mcp-* headers and the error taxonomy, and sessions. Every section names the test-servers/configs/*.json that reproduces it.
docs/tools/inspector/web	Session token, --dev, the full tab bar, the monitoring sidebar, Server Settings, per-tab walkthrough, deep links, host binding.
docs/tools/inspector/cli	Method table, --tool-arg coercion vs. --tool-args-json verbatim, --format json, --app-info, exit codes + the stderr error envelope, CI recipes, proxies.
docs/tools/inspector/tui	Tabs with accelerators (and why they're not all first letters), navigation keys, the loopback OAuth flow, TTY requirement.
docs/tools/inspector/configuration	The flag reference organized by owner rather than as one flat list: launcher (2 flags) → shared server-selection → web-only → cli+tui OAuth → cli-only. Plus --catalog vs. --config as its own comparison, the -- separator, and env vars attributed to the layer that reads them (launcher / cli+tui / web backend).
docs/tools/inspector/authorization	The flow end to end, the callback-URL table and the loopback hard requirement, mid-session re-auth and step-up, non-interactive/CI behavior, the web→CLI handoff (--use-stored-auth, --wait-for-auth, --print-handoff).
docs/tools/inspector/recipes	stdio vs. HTTP, importing an existing client config, reviewing an MCP App (the CLI-first flow from docs/mcp-app-review.md), Docker, hosting on a network, dev workflow.

Verified against source, not the READMEs alone: parse-launcher-argv.ts, each client's commander block, core/mcp/types.ts (era + StoredMCPServer), and InspectorView.tsx (tab list + monitor group).

prettier --check and the MDX comment check pass. The link checker (mint broken-links) couldn't run locally — mintlify refuses Node 25 — so internal links were verified by hand against the file tree; SEP references point at /seps/2243-http-standardization, /seps/2575-stateless-mcp, /seps/2663-tasks-extension.

Before the PR opens: screenshots

20 slots are marked in place with TODO: captions. Everything needed to capture them:

#	Page	Shot	Setup
1	protocol-eras	Server Settings, Protocol Era selector	any server
2	protocol-eras	Logs tab, legacy and modern (side by side)	logging-legacy-http.json / logging-modern-http.json
3	protocol-eras	Resources → Subscriptions with the Listening badge	subscriptions-modern-http.json
4	protocol-eras	Tasks tab, both eras	tasks-legacy-http.json / tasks-modern-http.json
5	protocol-eras	Pending-request modal on input_required + grouped MRTR conversation	mrtr-showcase-http.json, mrtr_confirm
6	protocol-eras	Tools sidebar Excluded (SEP-2243) divider + mirrored-headers panel	xmcpheader-modern-http.json
7	protocol-eras	Network tab Mcp-* headers + Protocol tab -32022 with data.supported	modern-network-http.json
8	web	Full tab bar, connected modern HTTP server	any modern config
9	web	Monitoring sidebar pinned beside Tools	any
10	web	Server Settings expanded (era, advertised extensions, roots)	advertised-extensions-http.json
11	web	Tools: argument form + rendered result	any
12	web	Resources: read + active subscription	subscriptions-legacy-http.json
13	web	Prompts: arguments + generated message preview	any
14	web	Apps: rendered widget, messages panel, app logs	an App-tool server
15	web	Protocol: request/response pair expanded	any
16	recipes	Servers screen import dialog	any client config file
17	tui	TUI Tools tab with a result	any
18	tui	TUI Auth tab	an OAuth HTTP server
19	authorization	Connection Info / Auth panel	an OAuth HTTP server
20	authorization	Re-authorization banner after a mid-session 401	staging OAuth server

Shots 1–16 land in docs/images/inspector/ in the docs-site repo; 17–18 are terminal captures.

Also fixed while in here: the duplicated Per-surface guides bullet in this issue's description.

[cliffhall]

Screenshots captured — 21 of the 22 slots

All shots are in docs/images/inspector/ on branch docs/inspector-v2 (commit a7599608), wired into the pages with real captions. No TODO markers remain.

How they were taken

Everything ran against this repo's own composable test servers, so each era-fork picture reproduces from a named config rather than a staged mock:

• Web + OAuth — driven headlessly through Playwright at 1920×1080 @2x against clients/web's Vite dev server.
• TUI — spawned in a real pty (Ink needs raw mode), keystrokes written to the pty, and the captured stream replayed through a terminal emulator to reconstruct the screen with its colors, then rendered to PNG. Plain-text scraping would have thrown the color away.
• OAuth — the full round trip is real: connect → 401 → DCR → the test AS consent page → callback → connected. oauth-step-up-demo.json on :8081.

Everything ran under an isolated HOME, so no real catalog entry, server URL, or token appears in any image.

What each shot shows

Image	Server config
settings-protocol-era	Era selector open with all three choices
logs-legacy / logs-modern	logging-legacy-http / logging-modern-http — Set Active Level vs. Log Level per Request, both with a live log
resources-subscriptions-modern	subscriptions-modern-http — the LISTENING badge
tasks-legacy / tasks-modern	tasks-*-http — modern shows resultType: complete inlined
mrtr-pending-request	mrtr-showcase-http — mrtr_confirm paused at the modal, tagged input_required
tools-sep2243	xmcpheader-modern-http — mirrored city → Mcp-Param-City beside the struck-through invalid_header_tool under Excluded (SEP-2243)
network-modern-headers / protocol-modern-error	modern-network-http — the 400 in Network, -32022 UnsupportedProtocolVersion + supported versions in Protocol
web-* (8)	tab bar, monitoring sidebar, server settings, tools, resources, prompts, apps, protocol
tui-tools / tui-auth	TUI Tools and Auth tabs
auth-connection-info	Connection Info after OAuth — AUTHORIZED, DCR client, granted scopes

The hero image on the overview page now shows the v2 client instead of the v1 screenshot it inherited.

The one that isn't there

The mid-session re-authorization banner. oauth-step-up-demo's authorization server grants every configured scope (mcp, tools:read, weather:read) on the initial DCR exchange, so calling the weather:read-gated get_temp succeeds outright and no step-up fires. Forcing it needs a server whose first grant deliberately withholds a scope. I dropped that frame rather than ship a misleading image; the prose section still stands on its own. Worth a follow-up if we want the picture.

Checks

prettier --check and the MDX comment check pass. Every /images/inspector/*.png reference resolves to a file on disk and no image is orphaned (verified by diffing referenced vs. present). mint broken-links still can't run locally — mintlify refuses Node 25 — so it will get its first real run in CI on the PR.

[cliffhall]

Docs-site PR is open: modelcontextprotocol/modelcontextprotocol#3143

Branch docs/inspector-v2, two commits — the prose rewrite, then the 21 screenshots. /docs/tools/inspector keeps its URL as the overview page, with the seven new pages nested under it in the Developer tools group.

Moving this card to In Review. Note it won't auto-close on merge (different repo), so it needs closing by hand once #3143 lands.