食谱 - MCP 中文文档

连接 stdio 与 HTTP 服务器

stdio

stdio 服务器是由 Inspector 启动的进程。所有位置参数都会作为命令行参数传入：

mcp-inspector node build/index.js -- --verbose --config /etc/myserver.conf

在所有要传递给服务器的参数之前加上 --。如果没有这个分隔符，--verbose 会被 Inspector 解析，无法传递给服务器。使用 -e 为进程设置环境变量，使用 --cwd 设置工作目录：

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

mcp-inspector --server-url https://api.example.com/mcp --transport http \
  --header "X-Tenant: acme"

--transport 接受 http（可流式 HTTP）和 sse。如果服务器受到保护，请参阅授权：无需提前进行设置，因为当服务器返回 401 时，Inspector 会运行其中所述的 OAuth 流程，然后重试连接。对于 HTTP 服务器，还需要确定其协议时代。默认值为 legacy；在服务器设置中设置为 modern 或 auto（或在目录文件中设置 protocolEra），即可体验 2026-07-28 的行为。

导入现有客户端配置

在服务器页面中，添加服务器可以导入您已在其他位置配置的 MCP 服务器，无需重新输入。它可以直接解析 Claude Desktop、Cursor、Cline 和 VS Code 客户端配置，也可以读取服务器自己的 MCP Registry server.json。导入会合并到当前启用的目录（Inspector 可写入的服务器列表）中，因此不会覆盖现有条目。如果您不想修改目录，也可以改为以只读方式针对外部文件启动：

mcp-inspector --config ~/Library/Application\ Support/Claude/claude_desktop_config.json

--config 可确保文件按原样提供服务，且不会被写入、植入或迁移。

审查 MCP 应用

MCP 应用是携带 UI 小组件的工具。对于自动化审查程序（CI 或代理），请对每项返回 JSON 的检查使用 CLI，仅在检查渲染后的小组件时打开浏览器。

不调用工具，探测安全状况

mcp-inspector --cli --transport http --server-url https://example.com/mcp \
  --method tools/call --tool-name <tool> --app-info

stdout 上输出一行 JSON；如果工具包含应用则退出码为 0，如果不包含则为 2，因此 && 链会短路：

{
  "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 会读取该资源。工具永远不会被调用。

获取完整结果载荷，仍然不使用浏览器

mcp-inspector --cli --transport http --server-url https://example.com/mcp \
  --method tools/call --tool-name <tool> --tool-args-json '{"zip":"10001"}' --format json

启动 Web Inspector 一次，仅限回环地址

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=<encoded url>&transport=http&autoConnect=<TOKEN>&openApp=<tool>&appArgs=<base64url(JSON)>&autoOpen=<TOKEN>

appArgs 是经过 base64url 编码的 JSON 工具参数，每个深层链接参数都在深层链接下进行了说明。autoConnect 和 autoOpen 必须都等于会话令牌，因为 autoOpen 会直接从 URL 触发工具调用，需要使用与 autoConnect 相同的权限门控。

等待确定性信号，而不是休眠

应用屏幕提供了稳定的自动化契约。请轮询以下属性，而不是休眠：

选择器	属性	值
`[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

已为 linux/amd64 和 linux/arm64 发布容器镜像到 GitHub Container Registry：

docker run --rm -p 6274:6274 ghcr.io/modelcontextprotocol/inspector

从容器日志中读取会话令牌，或使用 -e MCP_INSPECTOR_API_TOKEN=<value> 固定令牌。该镜像默认使用 --web，绑定到 0.0.0.0:6274，不自动打开浏览器，并以非 root 用户运行。由于容器必须绑定通配地址才能通过 -p 访问，因此它会设置 DANGEROUSLY_BIND_ALL_INTERFACES=true。其 HEALTHCHECK 会探测 Web UI，因此在运行 --cli 或 --tui 时请添加 --no-healthcheck（两者都没有 Web 服务器）。下面的 <target> 是一个临时目标：一个位置参数形式的 stdio 命令，或 --server-url <url> --transport http。

docker run --rm --no-healthcheck ghcr.io/modelcontextprotocol/inspector --cli <target> --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 主机源，因此请通过名称或 IPv4 地址访问。

无论采用哪种形式：都应保持身份验证开启。对于任何除了你本人之外的其他人都能访问的环境，切勿设置 DANGEROUSLY_OMIT_AUTH。

开发工作流

一个在实践中行之有效的循环：

从 CLI 开始

--method initialize 会确认服务器启动、完成握手并报告你所期望的功能，一秒内即可得到机器可读的结果。大多数“无法运行”的问题都出在这里。

转到 Web 客户端进行探索

由架构驱动的表单、渲染后的结果以及旁边的协议选项卡，让你可以快速找到工具行为异常的情况。

测试边界情况

无效输入、缺失的必需提示参数、并发调用，以及对于 HTTP 服务器的两种协议时代。确保这些错误和成功一样，都是经过有意设计的。

使用 CLI 固化结果

将你的发现转化为 CI 断言：将 CLI 的 --format json 输出通过管道传给 jq -e，并使用 --stored-auth-only，这样缺少令牌时会快速失败，而不是启动交互式 OAuth。有关完整命令，请参阅在 CI 中验证服务器。

开始使用

关于 MCP

使用 MCP 进行开发

开发者工具

示例

食谱

连接 stdio 与 HTTP 服务器

stdio

HTTP 和 SSE

导入现有客户端配置

审查 MCP 应用

Docker

在网络上托管

开发工作流

​连接 stdio 与 HTTP 服务器

​stdio

​HTTP 和 SSE

​导入现有客户端配置

​审查 MCP 应用

​Docker

​在网络上托管

​开发工作流

连接 stdio 与 HTTP 服务器

stdio

HTTP 和 SSE

导入现有客户端配置

审查 MCP 应用

Docker

在网络上托管

开发工作流