来源：MCP Inspector 仓库 · MCP 官方文档 · MCP Debugging | 整理时间：2026-04-11
为什么单独学 Inspector？
很多 MCP Server 不是“写不出来”，而是“调不明白”。
MCP Inspector 是官方调试器，能直接回答三个关键问题：
- 服务器到底暴露了哪些 tools/resources/prompts？
- 某个 tool 为什么调用失败？参数还是权限问题？
- 在真实客户端（Claude Code/Cursor）接入前，服务器是否可用？
Inspector 架构速览
[Browser UI : MCPI]
│ HTTP
▼
[Proxy : MCPP]
│ stdio / SSE / streamable-http
▼
[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 |
| SSE | 旧版远程服务 | http://localhost:3000/sse |
| streamable-http | 新版远程服务 | http://localhost:3000/mcp |
建议：新项目优先使用 streamable-http。
调试工作流（推荐）
- 先跑
tools/list，确认工具是否被正确注册。 - 再跑
tools/call，用最小参数验证 happy path。 - 故意传错参数，检查错误信息是否可读。
- 验证
resources/list与prompts/list，确保描述完整。 - 最后导出配置，接入 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。
常见问题排查
1) tools/list 为空
- 检查 server 启动入口是否执行了注册代码
- 检查是否连错 transport（stdio vs http）
2) tools/call 超时
- 增大
MCP_SERVER_REQUEST_TIMEOUT - 工具若有长耗时，增加进度通知并开启超时重置
3) 本地能跑，客户端连不上
- 先用 Inspector 导出的配置替换手写配置
- 检查环境变量是否随配置一起传递
4) 远程服务偶发 401
- 检查 Bearer Token 是否过期
- 校验自定义 header 名称是否一致
与其他调试方式对比
| 方式 | 优点 | 局限 |
|---|---|---|
| Inspector UI | 可视化强，适合开发调试 | 人工操作多 |
| Inspector CLI | 可脚本化，适合 CI | 可视化弱 |
| 直接客户端联调 | 贴近真实使用 | 定位问题成本高 |
最佳实践：本地用 UI 找问题，CI 用 CLI 防回归，最后再上客户端联调。