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

导入现有客户端配置

在“服务器”界面中，添加服务器可以导入您已在其他位置配置的 MCP 服务器，无需重新输入。它可以直接解析 Claude Desktop、Cursor、Cline 和 VS Code 客户端配置，也可以读取服务器自身的 MCP 注册表 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

标准输出中只有一行 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 使用相同的门控机制。

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

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 的容器镜像：

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

从容器日志中读取会话令牌，或使用 -e MCP_INSPECTOR_API_TOKEN=<value> 固定令牌。该镜像默认使用 --web，绑定到 0.0.0.0:6274，关闭浏览器自动打开，并以非 root 用户运行。它设置了 DANGEROUSLY_BIND_ALL_INTERFACES=true，因为容器必须绑定通配地址，才能通过 -p 访问。它的 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 host-source，因此请通过名称或 IPv4 地址访问。

无论采用何种方式：都要保持身份验证开启。对于任何可被除你之外的其他人访问的实例，切勿设置 DANGEROUSLY_OMIT_AUTH。

开发工作流

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

从 CLI 开始

--method initialize 会确认服务器启动、完成握手并报告你所期望的功能，整个过程只需一秒，并返回机器可读的结果。大多数“它无法运行”的问题都出在这里。

转到 Web 客户端进行探索

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

测试边界情况

测试无效输入、缺失的必需提示参数、并发调用，以及对于 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

在网络上托管

开发工作流