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: a747cccf3036a7c038ed42f0393363c44413785f971bbfe15eaab20c298eb937Use this token to authenticate requests or set DANGEROUSLY_OMIT_AUTHtrue to disable auth Open inspector with token pre-filled:http://localhost:6274/?MCP_PROXY_AUTH_TOKENa747cccf3036a7c038ed42f0393363c44413785f971bbfe15eaab20c298eb937 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 Server2.1连接 ServerInspector 界面左侧面板Transport Type选STDIOCommand填javaArguments填-jar /path/to/mcp-tools-server.jar换成你自己的路径点ConnectInspector 会帮你把 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选SSEURL填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.err4.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: trueInspector 里看到这个格式说明工具执行时抛了异常{ 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 和 PromptsTools 是最常用的但 MCP Server 还可以暴露 Resources 和 PromptsInspector 对这两个也支持调试顺带说一下。5.1 Resources点Resources标签看已注册的资源列表docs://handbook/onboarding—— 员工入职手册docs://api/overview—— API 接口文档总览config://app/production—— 生产环境配置点右侧Read直接读取验证内容是否正确。模板资源如db://orders/{orderId}填入参数后读取URI: db://orders/ORD202401150015.2 PromptsMCP Prompts 是可复用的提示词模板带参数调用时填参数生成最终 prompt。点Prompts标签看到提示词模板列表点code_review右侧Get填参数{ code: public void login(String user, String pass) { ... }, focus: security }查看生成的提示词内容对不对。六、推荐的调试流程每次改了工具代码按这个顺序走写工具代码mvn package打 jarMCP Inspector 连接看工具列表是否正确Inspector 手动调每个工具验证参数和返回值验证 Resources 和 Prompts如果有接入 Cursor 做端到端测试集成到 Spring Boot Agent 应用改了代码重新打包后Inspector 里点Reconnect不用重启 Inspector 界面很方便。Inspector 这个工具我强烈建议大家养成习惯——先 Inspector 验证再接 Cursor遇到问题心里有底不会一堆报错不知道从哪查起。