docs: update docs with session client (mcpdo), latest docker config, and secret storage on modelcontextprotocol.io #2450

Problem

The Inspector pages on modelcontextprotocol.io (written in #1803 as modelcontextprotocol/modelcontextprotocol#3143) say nothing about where the Inspector keeps secrets. #2447 / PR #2448 adds that guide to this repo and changes behavior the site should describe:

• A new MCP_INSPECTOR_SECRET_KEY_FILE variable reads the file-store passphrase from a file, for Docker and Compose secrets. If that file is missing, unreadable or empty, or if both key variables are set, the store refuses to read or write rather than falling back to plaintext.
• In Docker, mounting the data volume switches secrets from memory to a secrets.json file on the volume. That file is plaintext unless a key is supplied, and even encrypted it carries moderate risk. The threat model is spelled out in docs/secret-storage.md.

The site's Docker recipe does not mention the volume or secrets at all, so a user following it cannot learn any of this.

Proposal

Open a PR against modelcontextprotocol/modelcontextprotocol, the same shape as #3143, updating both doc versions, docs/docs/draft/tools/inspector/ and docs/docs/2026-07-28/tools/inspector/:

• configuration.mdx
  • Add a "Where secrets are stored" section: what is stored as a secret (not headers), the selection order (MCP_INSPECTOR_SECRET_STORE → OS keychain → memory/file fallback), the file location and encryption, and moving back to a keychain.
  • Add MCP_INSPECTOR_SECRET_STORE, MCP_INSPECTOR_SECRET_FILE, MCP_INSPECTOR_SECRET_KEY and MCP_INSPECTOR_SECRET_KEY_FILE to the environment-variables table.
• Loud callout for the host fallback, the case the site is most likely to miss. On a host with no OS keychain (Linux without libsecret or a Secret Service, headless or SSH sessions, Termux), the Inspector automatically stores secrets in ~/.mcp-inspector/secrets.json, which is plaintext unless a key is supplied. Mirror the [!WARNING] from docs/secret-storage.md (a Mintlify <Warning>) in configuration.mdx, with the three ways out: get a keychain back, encrypt with MCP_INSPECTOR_SECRET_KEY_FILE, or MCP_INSPECTOR_SECRET_STORE=memory. Add a short pointer to it from the inspector.mdx landing page or its installation section, matching the new README warning.
• recipes.mdx → Docker
  • Add the persistence volume and the <Warning> from docs/docker.md: a mounted volume turns on plaintext file storage unless a key is supplied.
  • Show the MCP_INSPECTOR_SECRET_KEY_FILE examples with docker run and with Compose secrets.
  • Link to the threat model.
• recipes.mdx → Docker, smaller point: the example publishes -p 6274:6274 on all host interfaces, while this repo's Docker guide uses -p 127.0.0.1:6274:6274. Align them.
• web.mdx, optional: mention the secret-storage footer in the Client Settings, Server Settings and Add/Edit/Clone server dialogs.

Source of truth: docs/secret-storage.md, docs/docker.md, docs/environment-variables.md and the README.md warning in this repo, as merged by #2448.

Note that the stderr fallback and caveat warnings now end with a link to docs/secret-storage.md on main. The site page should link to that guide as well, so a user who arrives from either side lands on the same content.

A dedicated Security section

Rather than scattering threat-model material across configuration.mdx and recipes.mdx, add a separate Security section to the Inspector docs on the site (both doc versions) that gathers all of the Inspector's threat-model information in one place. The configuration and recipe pages keep their short <Warning> callouts and link to it for the reasoning.

It should cover at least:

• Secret storage: the "what the file store protects against" analysis from docs/secret-storage.md, i.e. plaintext vs. encrypted, where the key lives, root and docker group access, and same-user processes.
• The automatic plaintext fallback on hosts with no keychain, stated as a risk rather than only as a configuration fact.
• Docker: binding the published port to 127.0.0.1 versus all interfaces, and what the persistence volume puts on disk.
• The web backend's API token and what DANGEROUSLY_OMIT_AUTH gives up.
• stdio servers run as the user: they get a short environment allowlist plus their configured env:, but can still read the secrets file and, usually, the Inspector's environment through /proc.

The mcpdo client's daemon

The mcpdo client (#1432) is expected in the 2.9.0 release and starts a background session daemon automatically on connect. That adds a long-lived local process holding live server connections, and the Security section needs to cover it in more depth than the mcpdo configuration and operation page will. At minimum:

• How clients reach it (socket, pipe or port), and who else on the machine can connect.
• How it authenticates the commands it accepts.
• What it holds in memory for its lifetime: live MCP connections, OAuth tokens, and any secrets it has resolved.
• Lifetime: when it starts, how it is stopped, and what happens to sessions when it exits or crashes.
• What it writes to disk: logs, state and lock files, and their permissions.

Write this against the daemon as it actually ships, so this part is blocked on #1432, not only on #2448.

Notes

• Blocked on feat: MCP_INSPECTOR_SECRET_KEY_FILE, and document secret storage for every runtime #2448 merging, so the site describes released behavior. The mcpdo daemon (mcpdod) coverage is also blocked on Inspector mcpdo client #1432.
• Like docs: new modelcontextprotocol.io Inspector documentation for v2 (legacy vs. modern era, more screenshots) #1803, the work happens in a different repo but is tracked here because it documents this Inspector.