MCP Inspector 调试——开发必备调试工具实战-深圳市維司達科技有限公司

今天来聊一个开发 MCP Server 必须知道的工具。

大家在写完工具代码打包 jar 之后，第一步不是直接接进 Cursor 测，因为 Cursor 出了问题你不知道是 Server 的问题还是 Cursor 本身的问题。我的习惯是先用MCP Inspector单独验证 Server——工具有没有注册上、参数传进去对不对、返回值格式对不对，全在 Inspector 里先跑一遍，没问题了再接进去。

一、安装和启动

不需要全局安装，一行 npx 搞定：

npx @modelcontextprotocol/inspector

第一次运行会下载包，稍等几秒。终端会打印：

Starting MCP inspector...
⚙️ Proxy server listening on 127.0.0.1:6277
🔑 Session token: a747cccf3036a7c038ed42f0393363c44413785f971bbfe15eaab20c298eb937
Use this token to authenticate requests or set DANGEROUSLY_OMIT_AUTH=true to disable auth
🔗 Open inspector with token pre-filled:
http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=a747cccf3036a7c038ed42f0393363c44413785f971bbfe15eaab20c298eb937
🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀

直接点终端里那个带 token 的链接打开浏览器，token 会自动填好。

如果手动访问http://localhost:6274出现Connection Error - Did you add the proxy session token in Configuration?，点左上角Configuration，把终端里的 Session token 粘贴进去，再重新连接即可。

二、调试 stdio MCP Server

2.1连接 Server

Inspector 界面左侧面板：

Transport Type选STDIO
Command填java
Arguments填-jar /path/to/mcp-tools-server.jar（换成你自己的路径）
点Connect

Inspector 会帮你把 Server 进程拉起来，完成 MCP 握手，然后右侧出现已连接的提示。

2.2查看工具列表

点Tools标签，能看到 Server 暴露的所有工具。

2.3手动触发工具调用

点querySales右侧的Run按钮，填入参数：

{ "startDate": "2024-01-08", "endDate": "2024-01-14" }

立刻看到返回：

{ "content": [ { "type": "text", "text": "2024-01-08 至 2024-01-14 销售数据：\n总销售额：¥128,450.00\n订单量：543 单..." } ], "isError": false }

右侧History面板同时显示完整的 JSON-RPC 通信记录，这里能看到协议层的原始消息，出了问题直接查这里。

三、调试 SSE MCP Server

比 stdio 还简单，填个 URL 就行：

Transport Type选SSE
URL填http://localhost:8090/sse
如果加了认证，在Headers里填X-API-Key: your-key
点Connect

后续操作和 stdio 完全一样。

四、常见问题排查

4.1连接失败、没有任何响应

十有八九是 Server 把 Spring Boot 日志打到 stdout 了。Inspector 去解析 JSON，结果第一行是2026-03-26 INFO ...，直接懵了。

排查方法：

# 直接跑一下 Server，看 stdout 有没有输出 java -jar mcp-server.jar # 如果看到了 Banner 或者日志，说明没配好 # 检查 logback-spring.xml 是否把 ConsoleAppender 的 target 改成了 System.err

4.2工具列表为空

# 检查启动日志（在 mcp-server.log 里） grep "ToolCallbackProvider" mcp-server.log # 或者加个临时 Bean 打一下 @Bean public ApplicationRunner debugTools(ToolCallbackProvider provider) { return args -> { System.err.println("注册的工具数量：" + provider.getToolCallbacks().length); }; }

4.3工具调用返回 isError: true

Inspector 里看到这个格式说明工具执行时抛了异常：

{ "content": [{ "type": "text", "text": "Error: 数据库连接失败..." }], "isError": true }

去工具方法里看业务逻辑，isError: true不是协议层的问题，是工具自己报错了。

4.4description 不对

在 Inspector 的工具详情里查inputSchema，确认参数描述、类型、required字段是否和代码里写的一致：

{ "name": "querySales", "description": "查询指定日期范围内的销售汇总数据...", "inputSchema": { "type": "object", "properties": { "startDate": { "type": "string", "description": "开始日期，格式 yyyy-MM-dd" } }, "required": ["startDate", "endDate"] } }

五、调试 Resources 和 Prompts

Tools 是最常用的，但 MCP Server 还可以暴露 Resources 和 Prompts，Inspector 对这两个也支持调试，顺带说一下。

5.1 Resources

点Resources标签，看已注册的资源列表：

docs://handbook/onboarding—— 员工入职手册
docs://api/overview—— API 接口文档总览
config://app/production—— 生产环境配置

点右侧Read直接读取，验证内容是否正确。
模板资源（如db://orders/{orderId}）填入参数后读取：

URI: db://orders/ORD20240115001

5.2 Prompts

MCP Prompts 是可复用的提示词模板，带参数，调用时填参数生成最终 prompt。点Prompts标签，看到提示词模板列表，点code_review右侧Get填参数：

{ "code": "public void login(String user, String pass) { ... }", "focus": "security" }

查看生成的提示词内容对不对。

六、推荐的调试流程

每次改了工具代码，按这个顺序走：

写工具代码
mvn package打 jar
MCP Inspector 连接，看工具列表是否正确
Inspector 手动调每个工具，验证参数和返回值
验证 Resources 和 Prompts（如果有）
接入 Cursor 做端到端测试
集成到 Spring Boot Agent 应用

改了代码重新打包后，Inspector 里点Reconnect，不用重启 Inspector 界面，很方便。

Inspector 这个工具我强烈建议大家养成习惯——先 Inspector 验证，再接 Cursor，遇到问题心里有底，不会一堆报错不知道从哪查起。

MCP Inspector 调试——开发必备调试工具实战