实战:路径与工作流

MCP Inspector 调试实战:本地开发、CLI 自动化与安全配置

更新 原创整合
标签
mcpdebugginginspectortutorial

为什么单独学 Inspector?

很多 MCP Server 不是“写不出来”,而是“调不明白”。

MCP Inspector 是官方调试器,能直接回答三个关键问题:

  • 服务器到底暴露了哪些 tools/resources/prompts?
  • 某个 tool 为什么调用失败?参数还是权限问题?
  • 在真实客户端(Claude Code/Cursor)接入前,服务器是否可用?

Inspector 架构速览

[Browser UI : MCPI]
      │ HTTP
      ▼
[Proxy : MCPP]
      │ stdio / streamable-http / legacy SSE
      ▼
[Your MCP Server]

说明:Proxy 既是一个 Web 服务,也是一个 MCP 客户端桥接层。


快速启动

UI 模式(最常用)

npx @modelcontextprotocol/inspector

默认端口:

  • UI: 6274
  • Proxy: 6277

如果你已有本地 server 构建产物:

npx @modelcontextprotocol/inspector node build/index.js

三种连接方式

连接方式 适用场景 示例
stdio 本地开发调试 node build/index.js
streamable-http 2026-07-28 远程服务 http://localhost:3000/mcp
SSE 仅用于兼容旧版远程服务 http://localhost:3000/sse

建议:新项目只用 streamable-http;SSE 只用来验证还没迁移的旧 Server。


2026-07-28 之后,Inspector 要验证什么

2026-07-28 正式版移除了 initialize / initialized 和 Mcp-Session-Id,把 MCP 改成了请求/响应无状态协议。Inspector 的调试重点也随之变化:不再看“握手有没有成功”,而是看“每个请求能不能独立成立”。

建议按这张清单逐项验证:

检查项 预期
Transport 远程 Server 使用 streamable-http;stdio 仍可用于本地
请求自描述 每个请求带协议版本、客户端身份和能力,不依赖前置握手
Header Mcp-Method 和 Mcp-Name 正确,且经过代理后没有丢失
Session 请求和响应里不再依赖 Mcp-Session-Id
工具目录 tools/list 返回稳定顺序,ttlMs / cacheScope 合理
补充输入 需要用户确认时走 MRTR:input_required + inputResponses 重试
长任务 走 Tasks 扩展,不靠一直占着连接
授权 iss 校验、CIMD 或兼容的 DCR 流程可用

如果你在 Inspector 里看到一个远程 Server 不返回 initialize,这不一定是坏了——2026-07-28 本来就没有这一步。先确认它的 transport 和协议版本,再判断是不是配置错误。


调试工作流(推荐)

  1. 先跑 tools/list,确认工具是否被正确注册。
  2. 再跑 tools/call,用最小参数验证 happy path。
  3. 故意传错参数,检查错误信息是否可读。
  4. 验证 resources/list 与 prompts/list,确保描述完整。
  5. 最后导出配置,接入 Claude Code 或 Cursor。

CLI 模式:用于自动化回归

# 列出工具
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

# 调用工具
npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call \
  --tool-name search_docs \
  --tool-arg query="MCP transport"

CI 中可用 CLI 做“协议冒烟测试”:每次合并前先跑一遍核心 tool 调用。


导出配置到客户端

Inspector UI 支持导出两类配置:

  • Server Entry:单个服务片段
  • Servers File:完整 mcp.json

示例(stdio):

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["build/index.js"],
      "env": {
        "API_KEY": "your-key"
      }
    }
  }
}

这能减少“手写配置导致连不上”的低级错误。


安全配置必须做

Inspector 文档明确强调 Proxy 具备本地进程执行能力,因此应按最低暴露面使用。

安全项 推荐配置 风险
认证 保持默认 token 认证 关闭认证会导致本机被恶意页面利用
绑定地址 默认 localhost 绑定 0.0.0.0 会暴露到局域网
允许来源 配置 ALLOWED_ORIGINS DNS Rebinding 可能导致跨站调用

不要在公共网络裸跑 Inspector Proxy。


排查 Inspector 问题

1) tools/list 为空

  • 检查 server 启动入口是否执行了注册代码
  • 检查是否连错 transport(stdio vs streamable-http)
  • 2026-07-28 Server 不返回 initialize 是正常的;先确认协议版本,不要按旧握手流程排查

2) tools/call 超时

  • 增大 MCP_SERVER_REQUEST_TIMEOUT
  • 工具若有长耗时,增加进度通知并开启超时重置

3) 本地能跑,客户端连不上

  • 先用 Inspector 导出的配置替换手写配置
  • 检查环境变量是否随配置一起传递

4) 远程服务偶发 401

  • 检查 Bearer Token 是否过期
  • 校验自定义 header 名称是否一致
  • 2026-07-28 之后,检查 iss 校验、CIMD / DCR 配置和 client credentials 是否绑定到了正确的 issuer

与其他调试方式对比

方式 优点 局限
Inspector UI 可视化强,适合开发调试 人工操作多
Inspector CLI 可脚本化,适合 CI 可视化弱
直接客户端联调 贴近真实使用 定位问题成本高

最佳实践:本地用 UI 找问题,CI 用 CLI 防回归,最后再上客户端联调。