MCP Inspector：官方工具教你测试调试MCP服务器

MCP Inspector 不替代你的测试：它把真实协议变成可检验的平面。用它来发现未声明的 tools、虚假 schema、不兼容的传输方式，以及你单元测试套件看不到的权限问题。

MCP Inspector 是官方用于检查、测试和调试 Model Context Protocol (MCP) 服务器的工具。关键词是 MCP Inspector；意图是技术性和实践性的：开发者想在把服务器交给 Claude Code、Cursor、VS Code 或自己的 Agent 之前，先验证一个真实服务器。

分两层使用。Web 界面适合发现一个 tool、查看参数并复现一个故障；CLI 模式才是你应该用来自动化测试 tools/list、代表性调用、资源和 prompts 的工具，在 CI 中运行。Agent host 不是测试套件：如果那是你第一个客户端，等你发现问题时已经太晚了。

我的立场：一个 MCP 服务器不是因为 Inspector 能连上一次就算准备好了。它准备好了，是当它的目录、schema、预期故障和授权限制都在一个没有真实密钥的环境中得到验证的时候。成功连接只是冒烟测试，不是质量的定义。

MCP Inspector 测试什么，不测试什么

Inspector 充当 MCP 客户端，提供三个平面：Web、CLI 和 TUI。它可以通过 stdio 打开一个本地进程，或连接远程 endpoint，协商相应版本，并执行列出 tools、资源和 prompts 或调用一个 tool 等操作。这测试的是协议和打包方式，而不是孤立的 TypeScript 函数。

它本身不测试你的业务授权、租户间隔离、模型决策的质量或背后提供商的行为。也不会把一个有副作用的 tool 变成安全的。它是合同层：确认服务器暴露的内容与你的承诺完全一致，并且在收到无效输入时能以有用的方式失败。

从 MCP 2026-07-28 开始，这个区别变得重要了。在现代流程中，手握 handshake initialize 被放弃，取而代之的是 server/discover；请求携带按调用为单位的 metadata，而 Streamable HTTP 在协议层面是无状态的。如果你维护的测试假设旧的会话，它们可能针对旧式 fixture 通过，但在现代客户端上失败。

Inspector 检查真实的协议对话；CI 决定该结果是否满足合同，如果不满足则将变更退回服务器。

打开 host 前的最低合同

先写一个小的、可审查的合同表。为每个 tool 声明：名称、描述、inputSchema、输出字段、效果、所需 scope、超时、最大元素数和可恢复错误。如果一个 tool 需要读取租户的工单，tenant_id 必须来自 token 或后端，而不是来自模型可以更改的参数。

对 resources 和 prompts 做同样的事情。资源必须有 URI、MIME 类型和你能验证的大小限制；prompt 必须声明强制参数，并且在示例中不过滤敏感信息。Inspector 允许你查询这些平面，但重要的断言存在于你的代码库中：将规范化响应与团队批准的合同进行比较。

不要对整个段落或随机 ID 做快照。对顺序、时间戳、trace 和临时 URL 做规范化处理；只断言客户端需要用来做决策的字段。巨大的快照会引入噪音，使重要回归淹没在合法变更中。

通过 CLI 实现可复现的冒烟测试

它对你有用吗？每周一次即可

我用 5 分钟的邮件为你总结开发者、Agent、MCP、安全和工作流方面的 AI 工具。用西班牙语撰写，无噪音。

对于 stdio 服务器，测试 wire protocol 最快的方式是把 Inspector 作为客户端运行，而不是启动窗口然后点击。下面的命令列出一个已编译构建的 tools；将 Node 和依赖锁定在 lockfile 中，以便 CI 和你的笔记本执行相同的产物。

{
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "mcp:tools": "npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list"
  }
}

这个命令测试进程能启动、不会用日志污染 stdout、以及响应 MCP 目录。在 CI 中将其重定向到工件 JSON、分析 exit code，并检查只有允许的 tools 出现。诊断日志输出到 stderr；在 stdout 中写调试文本会破坏 stdio，即使服务器本地看起来是健康的。

测试一次真实调用及其错误

tools/list 检测不到一个用错误参数注册的 tool 或一个过早使用的凭证。选择一个成功的 tool 案例和 fixture，以及至少两个故障：无效参数和授权被拒绝的决策。对于搜索 tool，你不需要 LLM：使用一个返回已知结果的假索引，验证经过验证的 structuredContent。

值得检查的内容

Inspector 的 CLI 允许用 --method tools/call、--tool-name 和 --tool-arg 调用一个 tool。将输入保存在仓库的一个文件或脚本中，这样 YAML 中就不会有转义且脆弱的 JSON。测试应该期望一个明确的错误响应或文档化的业务代码；不应该接受进程以任何包含 'denied' 的文本结束。

一个有用的模式是用两个测试身份测试相同的调用。第一个可以读取其租户下的文档；第二个收到 permission_denied，且响应不会泄露文档是否存在。这种断言同时保护了机密性和 Agent 体验质量：收到明确 403 的模型不应该重试十次。

兼容性：测试你发布的服务器，而不是你记忆中的那个

Inspector v2 与旧时代和现代的服务器共存。配置、flags 和指向服务器的方式相对于 v1 发生了变化，所以不要复制博客文章而不锁定版本，并阅读已安装包的帮助。官方仓库包含迁移指南：将它作为依赖更新的一部分来使用。

对于远程，测试 host 将看到的精确 URL 和传输方式。一个对 stdio 有效的 endpoint 不能证明 CORS、header、反向代理、Content-Type、认证或 HTTP 传输的要求。在现代 MCP 中，方法名和 header 允许网关和限速器在不需要检查 body 的情况下验证和路由；当 header 与请求不一致时，HTTP 测试应该失败。

保持一个小矩阵：支持的传输 × 协议版本 × 测试身份 × 操作。不需要在每次提交时测试市场上所有的 host。但确实需要为你声明支持的每个协议版本测试一次兼容性，并在升级 SDK 或 Inspector 时进行回归测试。

Inspector 也是一道安全边界

Inspector 的 Web 界面依赖一个能够启动进程和连接 MCP 服务器的本地代理。不要将它暴露在不可信的网络中，也不要为了避免开发麻烦而禁用其认证。该项目本身警告说，这种捷径可能允许恶意网页将你的机器作为通向本地进程的桥梁。

在 CI 中，针对使用无特权用户、临时目录和非敏感 fixture 的容器或临时进程运行 Inspector。不要通过 -e 传递生产 token，不要打印 Authorization header，也不要在 jobs 之间留下暴露的端口。对于远程服务器，使用具有最小 scope 的测试身份，并像对待其他集成密钥一样撤销它。

最有价值的负面测试不是奇异的 payload：而是确认 tool 无法扩大自己的权限。模拟一个请求另一个账户、私有 URL 或写操作的参数，并验证你的后端在 tool 到达提供商之前就强制执行了策略。

从 Inspector 到 CI 中的质量门

将 pipeline 分为四个短 job：编译和运行单元测试；用 fixture 启动服务器；运行 Inspector CLI 检查目录、tools、资源和 prompts；运行授权和限制的负面测试。将规范化的结果和协议版本作为工件保存，而不是凭证或用户上下文。

当公共 tool 消失、schema 变更而没有版本控制、安全调用返回了其他租户的数据、或进程在 stdout 上输出了垃圾时，阻止 merge。不要因为描述的cosmetic变化而阻止，只要语义合同仍然有效；否则团队会学会忽略红色警告。

协议测试必须与可观测性共存。分配一个测试 traceparent，记录 tool 名称、延迟、结果和以编辑方式记录的拒绝原因。当一个集成在真实 host 上失败时，你可以将 trace 与 CI 中相同操作关联起来，而不是让模型从一个对话中重建事件。

连接 Agent 前的检查清单

编译服务器并对产物而非未构建的源文件运行 Inspector CLI。

断言消费者真正使用的 tools、资源和 prompts，以及 schema 和限制。

用 fixture 测试一次成功调用，并控制 timeout 和上游故障。

测试两个测试身份并确认租户间、scope 间和可变操作的隔离。

在你声明支持的传输和协议版本的最小矩阵上运行测试。

保持 Inspector、服务器和 SDK 的版本控制；在从旧 MCP 时代更新时重新阅读迁移文档。

使用无生产密钥、无公共端口和无不必要的权限运行代理和 fixture。

将规范化的结果和编辑过的 trace 作为 CI 工件保存。

常见问题

什么是 MCP Inspector？

它是 MCP 生态系统的官方工具，用于通过 Web 界面、CLI 和 TUI 检查、测试和调试服务器。它充当 MCP 客户端来检查真实的协议对话。

MCP Inspector 能替代 Jest、pytest 或集成测试吗？

不能。它补充这些测试：验证你暴露的构建能正确地讲 MCP。业务规则、数据隔离、性能和外部提供商需要自己的测试。

我可以在 CI 中使用 MCP Inspector 吗？

可以，CLI 模式是为自动化设计的。针对临时进程或容器运行它，分析结果并保存编辑过的工件；不要将 Web UI 变成 CI 中的交互式步骤。

我应该禁用 Inspector 代理的认证吗？

不应该。代理可以启动本地进程并连接到服务器；将其限制在 localhost 并使用其认证。禁用它是一种风险，而不是优化。

为什么在升级到 2026-07-28 后 MCP 测试失败？

现代时代消除了 transport handshake 和会话。检查你的服务器承诺的版本，让客户端协商或固定一个显式矩阵，并更新旧的 fixture。

在有副作用的 tool 中我应该验证什么？

除了 schema，还要验证 scope、后端中的派生身份、幂等性、在适用时的人工确认、审计，以及其他租户的身份无法推断数据或执行该操作。

如何将 MCP Inspector 添加到 MCP 服务器的 CI 中

定义合同。记录具有 schema、效果、scope、限制和预期错误的公共 tools、资源和 prompts。

编译产物。运行服务器的构建并测试生成的二进制文件或文件，而不是不同的开发路径。

用 fixture 启动。在 stdio 或具有受控数据且无生产密钥的临时容器中启动服务器。

列出平面。运行 Inspector CLI 查询 tools、资源和 prompts，并将规范化的输出与批准的合同进行比较。

调用一个安全 tool。用有效参数执行一次代表性调用，并验证 structuredContent、限制和业务结果。

添加负面用例。测试无效 schema、timeout、提供商宕机和两个测试身份，以确认授权和隔离。

测试兼容性。在你声明支持的每个 MCP 传输和版本上重复，特别是在升级 SDK 或 Inspector 之后。

关闭环境。收集编辑过的 trace 和结果，停止临时进程，并在合同变更或数据泄露时让 job 失败。

资源

MCP Inspector：仓库和 CLI

MCP Inspector：从 v1 迁移到 v2

MCP：2026-07-28 规范

MCP TypeScript SDK：协议版本

MCP TypeScript SDK：迁移到 v2

MCP：安全最佳实践

你可能还感兴趣

MCP 在生产环境：安全和权限

MCP outputSchema 和 structuredContent

MCP 远程服务器的 OAuth 2.1

用于 UI 测试的 Playwright MCP

MCP Registry：发布和发现服务器

每周接收一次面向开发者的 AI 工具阅读

每周我用 5 分钟的邮件为你总结开发者、Agent、MCP、安全和工作流方面的 AI 工具。用西班牙语撰写，无噪音。