配方 - 模型上下文协议

连接 stdio vs. 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；在 Server Settings 中设置 modern 或 auto（或在目录文件中设置 protocolEra），以启用 2026-07-28 行为。

导入现有的客户端配置

在 Servers 界面上，Add Servers 可以导入你已经在别处配置好的 MCP 服务器，而不必重新输入。它可直接解析 Claude Desktop、Cursor、Cline 和 VS Code 客户端配置，并且还会读取服务器自己的 MCP Registry server.json。导入会合并到活动的目录（Inspector 的可写服务器列表），因此现有条目不会被覆盖。如果你根本不想触碰你的目录，可以改为以只读方式针对外部文件启动：

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

--config 保证该文件按原样提供，绝不被写入、初始化或迁移。

Add Servers 提供从现有客户端配置或从注册表 server.json 导入。

审查一个 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，当资源声明了它时）位于 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，仅 loopback

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 相同的门控。

等待一个确定性信号，而不是 sleep

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：

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（两者都没有 Web 服务器）时添加 --no-healthcheck。下面的 <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 时，浏览器的 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。

开发工作流

一个在实践中运行良好的循环：

从 CLI 开始

--method initialize 在一秒内以机器可读的答复确认服务器启动、握手，并报告你所期望的能力。大多数“它不工作”最终都出在这里。

转到 Web 客户端进行探索

schema 驱动的表单、渲染出的结果，以及它们旁边的 Protocol 标签页，让你能快速找到工具行为异常的情形。

测试边界情况

无效输入、缺失的必需提示参数、并发调用，以及对于 HTTP 服务器的两种协议时代。验证这些错误与成功一样出于设计意图。

用 CLI 将其固化

把你发现的东西变成一个 CI 断言：用 --stored-auth-only 将 CLI 的 --format json 输出通过管道传给 jq -e，这样缺失的令牌会快速失败，而不是启动交互式 OAuth。完整命令参见在 CI 中验证一个服务器。

开始使用

关于 MCP

使用 MCP 开发

开发者工具

配方

连接 stdio vs. HTTP 服务器

stdio

HTTP 和 SSE

导入现有的客户端配置

审查一个 MCP 应用

Docker

在网络上托管

开发工作流

​连接 stdio vs. HTTP 服务器

​stdio

​HTTP 和 SSE

​导入现有的客户端配置

​审查一个 MCP 应用

​Docker

​在网络上托管

​开发工作流

连接 stdio vs. HTTP 服务器

stdio

HTTP 和 SSE

导入现有的客户端配置

审查一个 MCP 应用

Docker

在网络上托管

开发工作流