docs: qualify the ad-hoc rule and fix the contradicting -- guidance

- The "nothing combines with an ad-hoc target" rule has a web exception:
  run-web.ts:130 exempts `--transport stdio`, so web ignores it rather
  than rejecting. Only cli/tui reject every `--transport`.
- mcp-server-configuration.md still said a leading-dash argument cannot
  reach a stdio server under --cli, the opposite of what the migration
  guide now says. The parser puts every pre-`--` token in targetArgs, so
  the guide is right; corrected the older section to match.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFXDQBEjvjCEBhmYkmw79a
This commit is contained in:
cliffhall 2026-08-10 20:53:45 -04:00
commit 8c9cf40211

View file

@ -128,7 +128,7 @@ npx @modelcontextprotocol/inspector --catalog ./mcp.json
npx @modelcontextprotocol/inspector
```
**Rules:** `--catalog` and `--config` are mutually exclusive, and neither combines with an ad-hoc target (a positional command, `--server-url`, or `--transport`). v1 silently preferred the config file; v2 tells you.
**Rules:** `--catalog` and `--config` are mutually exclusive, and neither combines with an ad-hoc target (a positional command, `--server-url`, or `--transport`). v1 silently preferred the config file; v2 tells you. One exception: the **web** client exempts `--transport stdio` from that check, so it survives alongside `--catalog`/`--config` (ignored rather than rejected) — the CLI and TUI reject every `--transport`.
If you export `MCP_CATALOG_PATH` in your shell, note that **web and TUI read it unconditionally** — so an ad-hoc invocation such as `mcp-inspector --tui node build/index.js` is rejected as a catalog/ad-hoc conflict. Unset it for that invocation. The CLI ignores the variable whenever an ad-hoc target is present.