MCP Server 上线前怎么检查用只读 Inspector 验证协议、Tools、Resources 和 Prompts接手过几个 MCP Server 项目之后我最大的体会是写一个能跑的 MCP Server 不难难的是让它经得起上线前的折腾。尤其是当你把 Blender MCP、Playwright MCP 这类工具接到客户端里或者像 Cursor 连接蓝湖 MCP 那样搞内部集成时协议层面任何一个小毛病都会在真实用户那边放大成“工具不可用”“连接直接断开”。所以我现在每次发布前都会用只读 Inspector 把协议、Tools、Resources、Prompts 挨个过一遍今天就把这套检查流程完整写出来。1. 上线前检查到底在查什么先搞懂 Inspector 的定位1.1 为什么非要用只读模式MCPModel Context Protocol服务器的本质是让大模型应用通过标准协议去调用外部工具、读取资源、渲染提示词。你可以把它理解成一个插座客户端只管插上去至于插座背后是电视还是冰箱它不关心只要协议对得上就行。正因如此上线前最怕的就是“协议对不上”或者“功能不完整”。但这里有个很现实的问题很多 MCP Server 在开发环境里跑得好好的一到检查环节就容易出乱子。比如你连的是开发库某个工具一调用就把测试数据改了或者某个 Resource 触发了写操作搞得到最后你分不清是代码 bug 还是检查动作本身破坏了环境。所以我的原则很明确能只读就别读写检查阶段的所有动作都应该无副作用。Inspector 本身就是为这个场景设计的。它是一个可视化调试客户端可以连接本地或远程的 MCP Server把协议交互过程完整展示出来。我用的方式是把它跑在只读环境里——连接一个独立的测试实例数据库用副本文件系统用临时目录所有 Tools 里涉及写操作的动作都通过环境变量禁用掉。这样整个检查过程就像医生做体检仪器不会给病人开刀但所有指标都能测出来。1.2 Inspector 能覆盖哪些检查维度简单说Inspector 可以帮你确认四件事协议握手是否正常、Tools 的定义和调用是否符合预期、Resources 是否能被正确发现和读取、Prompts 是否能按模板生成消息序列。这四件事正好对应了 MCP 协议里最核心的四大能力。不过要提醒一句Inspector 不是万能的。它能验证“协议层”的正确性但验证不了“业务层”的正确性。比如你的数学计算工具把加法算错了Inspector 只能看到工具返回了一个结果不会告诉你结果对不对。所以我的检查流程是两层并行的——Inspector 负责协议层另外一套基于真实业务数据的测试脚本负责逻辑层。上线前两个都过了才敢发布。2. 环境准备本地、远程、容器三种场景怎么连 Inspector2.1 从 npx 启动到连接成功Inspector 的启动方式非常直白官方包名是modelcontextprotocol/inspector用 npx 直接拉起来就行。但这里我强烈建议不要裸跑npx因为你可能需要指定 MCP Server 的启动命令和环境变量这就涉及参数传递的问题。我常用的启动命令是npx modelcontextprotocol/inspector \ --env DATABASE_URLpostgres://readonly:passlocalhost:5432/test_db \ --env DISABLE_WRITE_ACTIONStrue \ -- node /path/to/your/server/index.js注意--后面的部分那是你要连接的 MCP Server 的实际启动命令。Inspector 会以子进程方式拉起这个命令通过 stdio 和它通信。如果你连的是远程服务比如 SSE 或 Streamable HTTP 端点命令会变成这样npx modelcontextprotocol/inspector --url http://localhost:8080/mcp还有一点容易踩坑Inspector 本身是一个 Web 应用启动后会在本地起一个端口默认是 6274然后自动打开浏览器界面。如果你在远程服务器上跑记得加--port参数并做好端口转发不然本地浏览器访问不到。2.2 隔离环境的三个关键动作只读检查的前提是“环境隔离”这件事比看起来复杂。我有三个固定动作每次检查前都会执行第一数据库连接必须用只读账号或者独立测试库。最好的方式是直接给 Inspector 注入一个DATABASE_URL环境变量指向只读副本同时在 MCP Server 里检测到这个环境变量后禁用所有写相关的 Tool。第二文件系统操作要限制在临时目录。我会为检查专门建一个/tmp/mcp_inspect目录所有文件操作的根路径都指向这里。第三外部依赖要打桩。有些工具会调用第三方 API这些调用在检查时无法触发真实写入我会用 mock 服务替换掉真实端点。提示如果 MCP Server 支持配置热加载检查过程中改配置后重启要比在界面上反复重连更省时间。但重启后一定要重新跑一遍协议握手验证不要想当然觉得配置没变就没问题。3. 协议层验证从 initialize 到能力协商手把手看消息流3.1 initialize 握手必须关注的三个字段MCP 的协议交互从 initialize 开始这是客户端和服务端第一次真正意义上的对话。Inspector 的主面板会把这个过程的每一条 JSON-RPC 消息都展示出来而我最关注的是响应里的三个字段protocolVersion、capabilities和serverInfo。protocolVersion是协议版本协商的关键。如果客户端支持 2024-11-05 版本但服务端只响应 2024-10-07说明你的服务端版本偏旧某些新特性可能没法用。这里有个小技巧在 Inspector 里可以手动修改发送的 protocolVersion测试服务端的版本协商逻辑。比如发送一个超高版本号看服务端是直接报错还是优雅地降级到它支持的版本——真实客户端比如 Claude Desktop经常会发它自己支持的版本但你不能假设所有客户端都按同一套规则来。capabilities则决定了后续你能用哪些功能。tools、resources、prompts这三个能力项必须如实声明。我踩过的一个坑是服务端明明实现了 ListPrompts但 capabilities 里漏写了prompts结果客户端根本不会去调用 ListPrompts 接口功能直接对用户不可见。这种问题用眼晴看不出来只有用 Inspector 把握手消息逐字看过一遍才抓得到。3.2 工具发现与调用链路的完整验证协议握手通过后下一步就是验证 Tools 的发现和调用链路。在 Inspector 的 Tools 面板里你会看到服务端通过tools/list返回的所有工具定义。重点检查每个工具的name、description、inputSchema是否完整、准确。这里有个非常容易出问题的点inputSchema的 JSON Schema 定义必须严谨。很多 MCP Server 为了图省事把所有参数都定义成type: string结果客户端传给工具的数值参数全被转成了字符串工具内部再手动解析。短期看能用但一旦遇到嵌套对象或者数组参数这种惰性写法的坑就全暴露了。所以我在检查时会有意识地做三件事第一核对每个工具的参数名和描述是否和实际代码逻辑一致第二用 Inspector 手动填参数调用工具故意传错类型看服务端返回的错误信息是否友好第三验证工具调用的响应结构确保content数组里的内容格式符合协议要求。3.3 错误处理机制比正常流程更重要协议验证里最容易被忽略的是错误处理。我在用 Inspector 检查时会专门“制造”一些异常场景比如传一个缺少必填参数的调用请求传一个不存在的工具名在 Resource 读取时指向一个不存在的 URI在 Prompt 渲染时传一个模板中不存在的变量正确的行为是服务端返回一个结构化的 JSON-RPC 错误对象error.code和error.message都能帮助客户端定位问题。而我见过不少 MCP Server 在这种场景下直接抛一个未捕获的异常导致整个连接断开。如果你在 Inspector 里发现调用一个工具后连接直接挂了不用怀疑这个 bug 必须在上线前修掉。4. 逐项体检Tools、Resources、Prompts 的实操检查法4.1 Tools 面板从列表到调用全链路检查Tools 部分我习惯分三步来检查。第一步看列表完整性对照设计文档逐个核对工具是否存在、描述是否准确、参数是否符合预期。第二步是单工具调用测试在 Inspector 里手动构造参数并调用观察返回结果和耗时。第三步是边角场景测试比如空参数、超大参数、特殊字符参数看看服务端能否正确处理。关于参数构造我想多说一句。Inspector 的 Tools 面板会根据 inputSchema 自动生成一个参数编辑界面你可以直接在里面填值。我常用的测试参数方式是“先正常后极端”先用一个业务上完全正常的参数组合调用确认功能没问题然后故意传一个极端值比如让一个做文件读取的工具去读一个 10GB 的文件或者让一个做搜索的工具去搜一个超长字符串确认服务端不会因此崩溃。注意如果工具内部有超时机制检查时最好把超时时间调短不然一个卡住的工具调用会占用你大量检查时间。4.2 Resources 检查URI 设计是重中之重Resources 是 MCP 里比较特殊的一块它不像 Tools 那样主动提供服务而是暴露数据供客户端读取。检查 Resource 时的核心关注点是 URI 设计。一个标准的 Resource URI 大概长这样resource://orders/2024/order-001 resource://users/profile/42好的 URI 设计应该是可预测、可读、可枚举的。用 Inspector 检查时我会先看resources/list是否能返回完整的资源列表然后逐个验证resources/read是否能按 URI 正确读取内容。这里有个容易忽略的细节如果你的服务端支持resources/templates模板 URI 里的参数填充是否正确直接影响客户端发现资源的能力。我在实际项目里见过一个经典 bug服务端定义了模板resource://orders/{orderId}但实际读取时对orderId做了正则校验而客户端比如某些 AI 编辑器插件填充的orderId带 URL 编码导致请求失败。这种问题在 Inspector 里一试就能暴露但如果你只测了精确 URI 而忽略模板 URI上线后就会变成隐藏在角落里的炸弹。4.3 Prompts 检查消息模板的变量解析Prompts 是 MCP 里一个经常被冷落的能力但对 AI 应用来说恰恰是最能提升用户体验的。检查 Prompts 时我会关注三个方面第一prompts/list是否能正确枚举所有提示词模板。第二prompts/get在传入不同参数时生成的messages序列是否符合预期。第三模板里的变量解析是否正确——这里的变量不是指客户端传过来的参数而是指模板内部的插值逻辑。举个例子假设你有一个错误分析 Prompt定义如下{ name: analyze_error, arguments: [ { name: errorMessage, required: true } ] }那么在 Inspector 里调用prompts/get时传errorMessage和没传errorMessage返回的结果应该是两个不同层次一个成功返回完整消息序列另一个应该返回参数缺失的结构化错误。如果你的服务端在缺少参数时返回的是模棱两可的空消息客户端拿到后根本无法正确渲染用户感知就是“这个功能坏了”。4.4 消息序列的细节把控再往深挖一点Prompts 返回的 messages 结构其实很有门道。每个 message 里有两个关键字段role和content。role必须是user或assistantcontent则可以是纯文本也可以是结构化内容。我在检查时发现过一种很隐蔽的问题某些服务端会把content按字符串返回但协议要求content是一个对象数组每个对象需要有type字段。如果type缺失或值不合法部分客户端在处理时可能直接忽略这条消息而 Inspector 不会明确报错只会显示一个“无内容”的提示。这种问题只有靠经验才能发现因为它在协议层并不算硬性错误但却是实际使用中“Prompt 不生效”的真正元凶。所以我每次检查 Prompts 时都会把返回的 messages 逐条展开确认content.type字段存在且值合法。5. 安全与性能只读检查里的隐藏观察项5.1 敏感信息泄露排查用 Inspector 做只读检查有一个额外的好处你可以在消息流里直接看到服务端返回的原始数据。这意味着你可以顺便检查敏感信息泄露问题。比如某个 Resource 按设计应该返回脱敏后的用户信息但通过 Inspector 的响应面板你发现返回的 JSON 里赫然带着完整的手机号甚至身份证号。这种问题在单元测试里很难暴露因为测试用例用的都是伪造数据而 Inspector 连的是真实测试环境能直接反映生产级别的数据返回情况。我的做法是在检查清单里加一条“敏感字段扫描”重点看 email、phone、token、password 这类字段是否出现在响应数据中。如果出现立刻回到代码层面检查是否存在过度序列化的问题。5.2 响应体大小和调用耗时观测Inspector 界面会对每次工具调用显示耗时这个数据非常宝贵。虽然是只读检查但通过它你能初步判断每个工具的性能表现。我自己有个经验阈值大多数 MCP 工具调用应该在 1 秒内返回如果某个工具调用耗时超过 5 秒这个工具在上线后很可能会被客户端视为超时而反复重试导致资源浪费和服务端压力。遇到这种情况我会在检查报告里单独标注要求开发团队优化后再发布。另外还要看响应体大小。一个返回 20MB JSON 内容的 Resource 读取操作对于远程客户端来说是一场灾难。我在检查阶段会留意每个响应的体积如果发现异常巨大会要求开发团队增加字段筛选或分页能力。5.3 并发调用和连接稳定性最后提一个很多人忽略的检查项并发稳定性。只读检查模式非常适合做并发测试因为你不用担心并发调用会污染数据。我的做法是在 Inspector 里连续快速调用同一个工具 20 次或者同时打开多个工具页面并行调用观察服务端是否会出现连接中断、消息乱序、响应超时等问题。MCP Server 很多是单进程模型如果处理请求时阻塞了事件循环并发能力就会很差。提前在 Inspector 里做一轮压力测试能避免上线后用户一多就崩的尴尬。6. 常见问题与排查技巧实录6.1 连接失败排查速查表用 Inspector 检查 MCP Server 时连接失败是最常见的痛点。我把实际工作中遇到的各种情况整理成一张速查表现象可能原因排查思路启动后未打开浏览器端口被占用或启动参数错误用--port指定新端口检查是否有旧进程残留Inspector 显示连接成功但无数据服务端 stdout 被污染MCP 走 stdio 通信服务端里不能有 console.log连接后马上断开协议版本不兼容查看 initialize 响应中的 protocolVersion确认双方版本匹配远程连接超时防火墙或代理拦截了 SSE 请求用 curl 直接请求/mcp端点确认网络链路通畅工具调用无响应工具内部存在未捕获异常查看服务端日志检查是否有异步任务未处理这里我想重点说第二行服务端 stdout 被污染。MCP 基于 stdio 通信时协议消息通过 stdout 传递如果你在服务端代码里不小心写了console.log(debug)这行文本就会混进消息流里导致 JSON-RPC 解析失败。我在好几个项目里都碰到过这个问题排查过程特别折磨人因为服务端看着一切正常日志也打得很勤但 Inspector 就是连不上。后来我养成一个习惯凡是走 stdio 的 MCP Server所有调试日志强制走 stderr 或者文件日志绝不碰 stdout。6.2 Inspector 里最常见的三类异常用多了 Inspector你会发现异常也是有套路的。我总结下来最常见的三类异常是第一Method not found。这个错好排查八成是服务端 capabilities 声明不完整客户端根据能力声明发起了某个请求但服务端没实现对应方法。比如 capabilities 里声明了resources但实际没有注册 ListResources 的处理函数。第二Internal server error但服务端无日志。这种情况要留意是异步异常吞掉了。MCP Server 里如果工具处理函数里有 Promise 没有 catch错误信息可能不会正确返回给客户端而是变成一条空错误。我的排查办法是在服务端所有异步入口外统一加一个错误处理器把未捕获异常统一转成 JSON-RPC 错误。第三Connection closed且无其他信息。这种通常是服务端进程崩了。在只读检查场景下很可能是某个资源读取触发了段错误或内存溢出。我会用--node --inspect在 Inspector 里给 node 进程开调试端口崩溃时能拿到堆栈信息。6.3 让 Inspector 输出更多 debug 信息Inspector 虽然开箱即用但默认的日志级别对复杂问题可能不够。在启动 Inspector 时你可以通过环境变量让整个流程输出更多信息DEBUGmcp:* npx modelcontextprotocol/inspector \ -- node /path/to/your/server/index.js也可以针对特定模块开启调试DEBUGmcp:server,mcp:client npx modelcontextprotocol/inspector -- node index.js这条命令会把诊断信息打到终端里。我会在排查问题时基本常开一旦 Inspector 界面上看不到的关键错误信息终端里通常能找到。这个技巧对于排查“服务端收到消息但没响应”这类问题特别有用因为界面上只看到超时但终端里能看到服务端收到了什么、卡在了哪一步。7. 检查报告的整理与落地习惯7.1 每次上线前的检查清单参考随着做的 MCP Server 项目变多我把检查流程沉淀成了一组清单每次上线前按部就班过一遍哪怕是新项目也能快速摸清状态协议层检查项有这么几条initialize 响应里的 protocolVersion 是预期版本capabilities 声明的能力与实际实现一致工具调用、资源读取、提示词渲染都能返回结构正确的响应异常场景下错误码和错误消息可读。功能层检查项包括核心工具按设计文档逐项调用通过资源 URI 和模板 URI 都能正确读取内容提示词模板渲染结果与预期一致敏感数据字段在响应中不可见单次工具调用耗时和响应体大小在可接受范围。稳定性检查项有短时间并发调用下连接不中断连续调用 20 次以上无明显性能退化重启服务端后 Inspector 能正常重连关闭并重开 Inspector 后所有功能仍正常。这份清单我一直在用也在带着团队用。每次上线前的检查都得过完这列清单才能放行发布。7.2 如何把检查过程沉淀成团队流程最后说一个非技术但很重要的点Inspector 检查这件事一定要沉淀成文档和流程不能只靠某个人“有经验”。我的做法是在项目仓库里放一份MCP_INSPECT_CHECKLIST.md里面包含环境准备命令、检查步骤、上次发现的典型问题和解决办法。新成员接手项目时先照着这份文档跑一遍完整检查有任何新的发现就补录进去。这样两三个版本迭代下来检查能力就不是某个人脑子里的东西而是整个团队的手册了。如果你现在正在做 MCP Server或者正准备接入别人的 MCP Server我强烈建议你花一下午把 Inspector 这套流程摸熟。上线前多花这几个小时省下的是上线后用户反馈、Debug、紧急修复的那好几个工作日。