> ## Documentation Index > Fetch the complete documentation index at: https://mcp-zh.com/llms.txt > Use this file to discover all available pages before exploring further. # 配方 > 关于传输、导入配置、审查 MCP 应用、Docker 和网络托管的实用指南 ## 连接 stdio vs. 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/2026-07-28/tools/inspector/authorization)：无需预先设置，因为当服务器返回 `401` 时，Inspector 会运行那里所述的 OAuth 流程并重试连接。 对于 HTTP 服务器，还要决定其[协议时代](/docs/2026-07-28/tools/inspector/protocol-eras)。默认是 `legacy`；在 Server Settings 中设置 `modern` 或 `auto`（或在目录文件中设置 `protocolEra`），以启用 2026-07-28 行为。 ## 导入现有的客户端配置 在 Servers 界面上，**Add Servers** 可以导入你已经在别处配置好的 MCP 服务器，而不必重新输入。它可直接解析 Claude Desktop、Cursor、Cline 和 VS Code 客户端配置，并且还会读取服务器自己的 [MCP Registry](/registry/about) `server.json`。 导入会合并到活动的[目录](/docs/2026-07-28/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 ``` stdout 上一行 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`，当资源声明了它时）位于 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/2026-07-28/tools/inspector/web#deep-links)下有说明。`autoConnect` 和 `autoOpen` 必须都等于会话令牌，因为 `autoOpen` 直接从 URL 触发一次工具调用，需要与 `autoConnect` 相同的门控。 Apps 界面暴露一个稳定的自动化契约。轮询这些属性，而不是 sleep： | 选择器 | 属性 | 取值 | | ----------------------------------- | ----------------- | ------------------------------------------------------------------- | | `[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/2026-07-28/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`（两者都没有 Web 服务器）时添加 `--no-healthcheck`。下面的 `` 是一个[临时目标](/docs/2026-07-28/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` 时，浏览器的 origin 变成 `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`，且其后端会启动进程，因此将其暴露到网络应被视为一个刻意的决定。 Inspector 拒绝绑定**通配符**全接口地址（`0.0.0.0`、`::` 以及每一种等价写法），除非你设置 `DANGEROUSLY_BIND_ALL_INTERFACES=true`。绑定一个**特定**地址无需选择加入即被允许，因为那是一次刻意的暴露，而不是一次性暴露每个接口——后者正是 DNS 重绑定攻击所针对的形态。 | 目标 | 该怎么做 | | -------------------- | -------------------------------------------------------------------------------------------------- | | **从 LAN 上的另一台机器访问它** | `HOST=192.168.1.50`。默认的 origin 允许列表跟随绑定主机，因此 `http://192.168.1.50:6274` 无需进一步配置即被接受。 | | **在 TLS 或反向代理之后** | 浏览器的 `Origin` 变成公共 origin，它不会与绑定主机匹配。设置 `ALLOWED_ORIGINS=https://inspector.example.com`。 | | **通配符绑定（容器）** | 设置 `DANGEROUSLY_BIND_ALL_INTERFACES=true`。Loopback 访问仍然开箱即用；在非 loopback 地址访问它需要 `ALLOWED_ORIGINS`。 | `ALLOWED_ORIGINS` **替换**默认列表，而不是与之合并。列出你将从中浏览的每一个 origin，包括你想保留的 loopback 形式： ``` ALLOWED_ORIGINS=http://localhost:6274,http://127.0.0.1:6274,http://192.168.1.50:6274 ``` 每个条目都必须包含 scheme；无 scheme 的值会被丢弃并给出警告。空值**不会**禁用该检查；它会回退到默认。没有关闭 origin 校验的开关。 脱离 loopback 时还有两个注意事项： * **MCP 应用也需要其沙箱端口可达。** 它是一个单独的、默认动态的端口；用 `MCP_SANDBOX_PORT` 固定它并暴露或转发它。Docker 镜像只发布 `6274`。 * **MCP 应用无法在 TLS 上或裸 IPv6 字面量处渲染。** 沙箱 URL 始终是纯 `http`，因此一个 `https://` 页面会将该 iframe 作为混合内容阻止；而带方括号的 IPv6 字面量不是有效的 CSP host-source，因此请在一个名称或一个 IPv4 地址处浏览。 无论何种形态：保持身份认证开启。不要在任何除你之外任何人可达的东西上设置 `DANGEROUSLY_OMIT_AUTH`。 ## 开发工作流 一个在实践中运行良好的循环： `--method initialize` 在一秒内以机器可读的答复确认服务器启动、握手，并报告你所期望的能力。大多数“它不工作”最终都出在这里。 schema 驱动的表单、渲染出的结果，以及它们旁边的 Protocol 标签页，让你能快速找到工具行为异常的情形。 无效输入、缺失的必需提示参数、并发调用，以及对于 HTTP 服务器的两种协议时代。验证这些*错误*与成功一样出于设计意图。 把你发现的东西变成一个 CI 断言：用 `--stored-auth-only` 将 CLI 的 `--format json` 输出通过管道传给 `jq -e`，这样缺失的令牌会快速失败，而不是启动交互式 OAuth。完整命令参见[在 CI 中验证一个服务器](/docs/2026-07-28/tools/inspector/cli#verify-a-server-in-ci)。