> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 配方
> 关于传输方式、配置导入、MCP 应用审核、Docker 和网络托管的实用指南
## 连接 stdio 与 HTTP 服务器
### stdio
stdio 服务器是由 Inspector 启动的进程。所有位置参数都会作为命令行参数传递：
```bash theme={null}
mcp-inspector node build/index.js -- --verbose --config /etc/myserver.conf
```
请在所有要传递给服务器的参数前加上 `--`。如果没有分隔符，`--verbose` 会被 Inspector 解析，而不会传递给服务器。
使用 `-e` 为进程设置环境变量，并使用 `--cwd` 设置工作目录：
```bash theme={null}
mcp-inspector -e API_KEY=abc123 -e REGION=us-east-1 --cwd ~/projects/my-server \
node build/index.js
```
服务器的 `stderr` 会显示在 **Console** 标签页（Web）或 Console 标签页（`o`，TUI）中。大多数 stdio 服务器都会将诊断信息输出到这里，因此当连接无明显原因失败时，请先检查该处。
### HTTP 和 SSE
```bash theme={null}
mcp-inspector --server-url https://api.example.com/mcp --transport http \
--header "X-Tenant: acme"
```
`--transport` 接受 `http`（Streamable HTTP）和 `sse`。如果服务器受到保护，请参阅[授权](/docs/draft/tools/inspector/authorization)：无需提前进行任何设置，因为当服务器返回 `401` 时，Inspector 会运行其中所述的 OAuth 流程，然后重试连接。
对于 HTTP 服务器，还需要确定其[协议时代](/docs/draft/tools/inspector/protocol-eras)。默认值为 `legacy`；在服务器设置中设置为 `modern` 或 `auto`（或在目录文件中设置 `protocolEra`），即可体验 2026-07-28 的行为。
## 导入现有客户端配置
在“服务器”界面中，**添加服务器**可以导入您已在其他位置配置的 MCP 服务器，无需重新输入。
它可以直接解析 Claude Desktop、Cursor、Cline 和 VS Code 客户端配置，也可以读取服务器自身的 [MCP 注册表](/registry/about) `server.json`。
导入内容会合并到当前激活的[目录](/docs/draft/tools/inspector/configuration#choosing-servers)
（Inspector 可写入的服务器列表）中，因此不会覆盖现有条目。如果您不想修改目录，也可以改为以只读方式针对外部文件启动：
```bash theme={null}
mcp-inspector --config ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
`--config` 可确保文件按原样提供服务，并且永远不会被写入、初始化或迁移。
## 审查 MCP 应用
[MCP 应用](/extensions/apps/overview)是携带 UI 小组件的工具。对于自动化审查程序（CI 或智能体），所有返回 JSON 的检查都使用 CLI，仅在检查渲染后的小组件时打开浏览器。
```bash theme={null}
mcp-inspector --cli --transport http --server-url https://example.com/mcp \
--method tools/call --tool-name --app-info
```
标准输出中只有一行 JSON；如果工具包含应用则退出码为 `0`，否则为 `2`，因此 `&&` 链会短路：
```json theme={null}
{
"hasApp": true,
"toolName": "get_pros",
"resourceUri": "ui://pros/view.html",
"csp": { "connectDomains": ["https://api.example.com"] },
"permissions": { "clipboard": false },
"prefersBorder": true,
"resourceMimeType": "text/html"
}
```
`csp` 和 `permissions`（以及资源声明了 `domain` 时的 `domain`）位于 UI **资源**上，而不是工具上，因此 `--app-info` 会读取该资源。工具绝不会被调用。
```bash theme={null}
mcp-inspector --cli --transport http --server-url https://example.com/mcp \
--method tools/call --tool-name --tool-args-json '{"zip":"10001"}' --format json
```
```bash theme={null}
TOKEN="$(openssl rand -hex 24)"
HOST=127.0.0.1 CLIENT_PORT=6274 MCP_SANDBOX_PORT=6275 \
MCP_AUTO_OPEN_ENABLED=false MCP_INSPECTOR_API_TOKEN="$TOKEN" \
mcp-inspector --web &
```
在此处固定 `MCP_SANDBOX_PORT` 很重要：应用的 UI 从一个独立的沙箱端口提供服务，该端口默认是动态的，而你的自动化程序需要通过固定地址访问它。
```
http://127.0.0.1:6274/?serverUrl=&transport=http&autoConnect=&openApp=&appArgs=&autoOpen=
```
`appArgs` 是经过 base64url 编码的 JSON 格式工具参数，每个深层链接参数都在[深层链接](/docs/draft/tools/inspector/web#deep-links)下进行了说明。`autoConnect` 和 `autoOpen` 必须都等于会话令牌，因为 `autoOpen` 会直接从 URL 触发工具调用，需要与 `autoConnect` 使用相同的门控机制。
Apps 屏幕提供了稳定的自动化契约。请轮询以下属性，而不是进行休眠：
| 选择器 | 属性 | 值 |
| ----------------------------------- | ----------------- | ------------------------------------------------------------------- |
| `[data-testid="apps-form"]` | `data-app-status` | `ready`（失败时，`data-app-error` 携带原因） |
| `[data-testid="connection-status"]` | `data-status` | `connecting`，随后为 `connected` 或 `error`（`data-error-message` 包含详细信息） |
| `[data-testid="connection-status"]` | `data-deeplink` | `parsed`、`rejected` 或 `none`（`none` 表示未提供深层链接，`rejected` 表示深层链接被拒绝） |
## Docker
GitHub Container Registry 中发布了适用于 `linux/amd64` 和 `linux/arm64` 的容器镜像：
```bash theme={null}
docker run --rm -p 6274:6274 ghcr.io/modelcontextprotocol/inspector
```
从容器日志中读取[会话令牌](/docs/draft/tools/inspector/web#the-session-token)，或使用 `-e MCP_INSPECTOR_API_TOKEN=` 固定令牌。
该镜像默认使用 `--web`，绑定到 `0.0.0.0:6274`，关闭浏览器自动打开，并以非 root 用户运行。它设置了 `DANGEROUSLY_BIND_ALL_INTERFACES=true`，因为容器必须绑定通配地址，才能通过 `-p` 访问。
它的 `HEALTHCHECK` 会探测 Web UI，因此在运行 `--cli` 或 `--tui` 时请添加 `--no-healthcheck`（两者都没有 Web 服务器）。下面的 `` 是一个[临时目标](/docs/draft/tools/inspector/configuration#ad-hoc-targets)：一个位置参数形式的 stdio 命令，或 `--server-url --transport http`。
```bash theme={null}
docker run --rm --no-healthcheck ghcr.io/modelcontextprotocol/inspector --cli --method tools/list
```
**如果重新映射发布的端口，请设置 `ALLOWED_ORIGINS`。** 使用 `-p
8080:6274` 时，浏览器的来源会变为 `http://localhost:8080`，这与
容器内的端口不再匹配，因此连接会返回 `403`。可以运行 `-e
CLIENT_PORT=8080 -p 8080:8080`，或者设置 `-e
ALLOWED_ORIGINS=http://localhost:8080,http://127.0.0.1:8080`。
## 在网络上托管
Inspector 默认绑定到 `localhost`，并且其后端会生成进程，因此应将其暴露到网络视为一项需要慎重决定的操作。
除非设置 `DANGEROUSLY_BIND_ALL_INTERFACES=true`，否则 Inspector 拒绝绑定**通配符**全接口地址（`0.0.0.0`、`::` 以及所有等效写法）。绑定**特定**地址无需选择加入，因为这只会有意暴露一个地址，而不是一次性暴露所有接口；DNS 重绑定攻击正是针对后者。
| 目标 | 操作 |
| ------------------ | ------------------------------------------------------------------------------------------ |
| **从局域网中的另一台机器访问** | `HOST=192.168.1.50`。默认的源允许列表会跟随绑定主机，因此无需进一步配置即可接受 `http://192.168.1.50:6274`。 |
| **位于 TLS 或反向代理之后** | 浏览器的 `Origin` 会变为公共源，这与绑定主机不匹配。设置 `ALLOWED_ORIGINS=https://inspector.example.com`。 |
| **通配符绑定（容器）** | 设置 `DANGEROUSLY_BIND_ALL_INTERFACES=true`。开箱即用仍可通过回环地址访问；通过非回环地址访问则需要设置 `ALLOWED_ORIGINS`。 |
`ALLOWED_ORIGINS` 会**替换**默认列表，而不是与其合并。请列出你会从中访问的每个源，包括你希望继续保留的回环地址形式：
```
ALLOWED_ORIGINS=http://localhost:6274,http://127.0.0.1:6274,http://192.168.1.50:6274
```
每个条目都必须包含协议；不含协议的值会被丢弃，并显示警告。空值**不会**禁用检查，而是回退到默认值。没有任何选项可以关闭源验证。
脱离回环地址时，还需注意以下两点：
* **MCP Apps 还需要其沙箱端口可访问。** 这是一个默认动态分配的独立端口；请通过 `MCP_SANDBOX_PORT` 固定该端口，并对其进行暴露或转发。Docker 镜像仅发布 `6274`。
* **MCP Apps 无法通过 TLS 或裸 IPv6 字面量渲染。** 沙箱 URL 始终使用纯 `http`，因此 `https://` 页面会因混合内容而阻止 iframe；带方括号的 IPv6 字面量也不是有效的 CSP host-source，因此请通过名称或 IPv4 地址访问。
无论采用何种方式：都要保持身份验证开启。对于任何可被除你之外的其他人访问的实例，切勿设置 `DANGEROUSLY_OMIT_AUTH`。
## 开发工作流
一个在实践中行之有效的循环：
`--method initialize` 会确认服务器启动、完成握手并报告你所期望的功能，整个过程只需一秒，并返回机器可读的结果。
大多数“它无法运行”的问题都出在这里。
由架构驱动的表单、渲染后的结果以及旁边的 Protocol 选项卡，让你可以快速找到工具行为异常的情况。
测试无效输入、缺失的必需提示参数、并发调用，以及对于 HTTP 服务器的两种协议版本。确认这些*错误*和成功一样，都是经过有意设计的。
将你的发现转化为 CI 断言：将 CLI 的 `--format json` 输出通过管道传给 `jq -e`，并使用 `--stored-auth-only`，这样缺失令牌时会立即失败，而不是启动交互式 OAuth。完整命令请参阅[在 CI 中验证服务器](/docs/draft/tools/inspector/cli#verify-a-server-in-ci)。