如何测试 MCP 工具的接入效果核对工具发现、参数校验与错误响应具体问题与完成目标你照着 MCP 官方文档或 SDK 示例写好了一个工具服务器启动后看起来一切正常。但当客户端连上来时你发现模型要么根本“看不到”你注册的工具要么在参数明显错误时仍然把请求发到了你的 handler 里要么工具抛出异常后客户端直接断开而没有给出任何可读的错误信息。这类问题的根源往往不在业务逻辑而在协议层面的接入质量工具发现是否完整、输入参数是否在到达 handler 之前就被正确校验、错误是否按照 MCP 约定的两种机制返回。本文用一个最小工具服务器作为案例给出一套可以手工执行的核对方法分别验证tools/list的返回是否包含你声明的全部工具、参数校验是否在正确的位置发生、以及协议错误与执行错误是否落在正确的通道。完成后你应当能对任何一个 MCP 工具服务器做一轮基础的接入验收而不是只凭“客户端能连上”来判断。适用环境本文以 Python 3.10 和 MCP Python SDK 为参考实现。SDK 当前有 v1 和 v2 两条线API 有差异。本文描述的是协议层面的可观察行为核对手法与具体 SDK 版本解耦——你可以在任何实现了 MCP 工具能力的服务器上使用。前置知识你需要知道 MCP 的基本通信模型客户端与服务器通过 JSON-RPC 消息交换以及“工具”在 MCP 中是什么一个由名称唯一标识、带输入 schema 的、可以被模型发现和调用的能力单元。案例背景与最小工具服务器假设你维护一个内部课程资料服务器的 MCP 接入层其中有一个工具search_course_material用于按关键词查询课程资料。你刚刚完成实现需要在上线前确认它的接入质量。案例输入是一个虚构的课程资料索引全部数据在文章内给出不依赖外部文件或数据库资料 ID关键词标题类型M001“MCP”MCP 协议入门文档M002“JSON-RPC”JSON-RPC 错误码速查文档M003“工具发现”MCP 工具发现机制视频M004“参数校验”输入 schema 设计指南文档工具定义如下名称search_course_material描述按关键词搜索课程资料返回匹配的资料列表inputSchema接受一个必需的字符串参数keyword长度 1–64这个工具足够小所有行为都可以手工复核。下面逐个给出核对的三个维度。核对一工具发现——tools/list返回了什么工具发现是接入的第一个可观察点。客户端在调用任何工具之前会先发tools/list请求服务器返回它声明的工具列表。如果这一步返回的内容与你的实现意图不一致后续所有测试都是在错误的前提上进行的。测试目标确认tools/list返回的工具定义在名称、输入 schema 和描述三个字段上都与你注册的意图一致。输入与操作构造一个tools/list请求JSON-RPC 格式发给你的服务器{jsonrpc:2.0,id:1,method:tools/list,params:{}}预期结果返回的result.tools数组中包含一个对象其关键字段应当满足字段预期值核对依据namesearch_course_material只使用字母、数字、下划线、连字符和点不含空格或特殊字符description非空字符串说明工具用途描述是模型判断是否调用该工具的主要依据inputSchema.typeobject有参数的工具的 schema 必须描述一个对象inputSchema.properties.keyword.typestring参数keyword的类型声明inputSchema.required包含keyword标记哪些参数是必需的判定方法逐字段比对返回的实际值与上表。如果name中包含空格或大写字母混用工具名是大小写敏感的或者inputSchema不是合法的 JSON Schema 对象例如为null则工具发现存在缺陷后续的参数校验测试将不可靠。边界情况如果你的服务器声明了多个工具tools/list可能支持分页返回中会包含nextCursor。一个常见的接入问题是工具总数超过一页的容量时客户端只拿到了第一页导致部分工具“消失”。边界测试是确认你的工具列表是否可能触发分页以及客户端是否会跟进nextCursor。如果你的工具总数远小于一页这个风险可以忽略如果接近分页阈值应当手工检查第二页的内容是否被正确返回。核对二参数校验——错误发生在哪里MCP 工具的参数校验有一个容易混淆的点校验应该发生在哪里以及错误应该以什么形式返回。MCP 协议定义了两种错误通道协议错误Protocol Errors标准的 JSON-RPC 错误例如-32602Invalid params。这类错误表示请求本身在协议层面就是非法的工具 handler 根本不应该被调用。工具执行错误Tool Execution Errors工具被调用了但在执行业务逻辑时失败通过工具结果中的isError: true返回。参数校验属于第一类。当模型或客户端发送的arguments不符合inputSchema时正确的行为是在调用 handler 之前就拒绝请求返回协议错误而不是让 handler 去处理一个非法输入。测试目标确认非法参数被拒绝的时机和形式拒绝发生在 handler 执行之前且返回的是协议错误而非isError结果。正常场景发送一个合法调用{jsonrpc:2.0,id:2,method:tools/call,params:{name:search_course_material,arguments:{keyword:MCP}}}预期结果返回一个工具结果content中包含匹配的资料。基于案例数据关键词 “MCP” 应当匹配到资料 M001 和 M003。边界场景空字符串发送arguments: { keyword: }。inputSchema声明了keyword的minLength为 1如果 schema 中未声明minLength则空字符串在 schema 层面是合法的此测试的预期会不同。预期结果如果 schema 中确实有minLength: 1的约束请求应当在 handler 之前被拒绝返回协议错误码-32602。失败场景缺少必需参数发送arguments: {}不含keyword。预期结果由于keyword在required列表中请求应当被拒绝返回协议错误-32602。判定方法检查返回的 JSON 中是否存在顶层error字段以及error.code是否为-32602。如果返回的是result中包含isError: true则说明校验发生在 handler 内部而非协议边界这是不理想的——它把参数校验的职责混入了业务逻辑也让错误类型失去了区分度。核对三错误响应——两种错误的归属工具被正确调用后执行过程中仍可能失败。此时需要确认错误是否以正确的机制返回。测试目标确认业务执行失败返回为工具执行错误isError: true而非协议错误确认未知工具名返回为协议错误。失败场景 A工具内部抛出异常在 handler 中人为加入一个触发条件例如当keyword等于__force_error__时抛出RuntimeError然后调用{jsonrpc:2.0,id:3,method:tools/call,params:{name:search_course_material,arguments:{keyword:__force_error__}}}预期结果请求格式合法、参数符合 schema因此它应当到达 handler。handler 抛出异常后服务器应当将其转换为工具执行错误返回一个result其中isError: truecontent中包含错误描述文本。不应返回顶层error字段。失败场景 B调用不存在的工具发送name: nonexistent_tool。预期结果返回协议错误。根据 MCP 规范未知工具属于协议错误通常对应 JSON-RPC 的-32601Method not found或实现定义的错误码。具体错误码可能因服务器实现而异但关键特征是顶层存在error字段而非result。可操作的验收表将上述核对接入一个可复用的验收表。每一行是一个独立测试不依赖其他测试的执行顺序。编号测试目的输入或操作预期结果判定方法T1工具发现完整性tools/list请求返回search_course_material的定义含非空name、description、合法inputSchema逐字段比对返回内容与注册意图T2正常调用keyword: MCP返回 M001 和 M003 的匹配结果检查content中是否包含这两个资料标题T3边界空字符串keyword: 协议错误-32602前提是 schema 含minLength: 1顶层有errorcode为-32602T4边界缺少必需参数arguments: {}协议错误-32602顶层有errorcode为-32602T5失败handler 异常keyword: __force_error__工具执行错误result.isError true无顶层errorT6失败未知工具name: nonexistent_tool协议错误顶层有error非resultT1 和 T6 核验的是工具发现与调用的协议边界T3 和 T4 核验参数校验的归属T2 和 T5 核验正常路径与执行失败的区分。如果 T3/T4 返回了isError结果说明你的服务器把校验放错了位置如果 T5 返回了协议错误说明 handler 异常被错误地提升到了协议层。常见故障的定位现象客户端看不到工具。先确认tools/list的原始响应。如果响应本身正常问题可能在客户端侧的解析或展示如果响应为空检查服务器是否正确声明了tools能力。现象参数错误时客户端收到isError而不是协议错误。这通常意味着你的 SDK 或框架把参数校验放在了 handler 内部。核对你的框架文档校验应该在tools/call的协议层完成而非由业务代码负责。现象handler 异常导致连接断开。在 handler 外层捕获所有异常并转换为isError: true的工具结果。协议层不应当因为业务逻辑的异常而终止连接。验证状态本文的核对手法基于 MCP 规范中关于工具定义、inputSchema和错误机制的公开描述。案例中的资料数据为虚构错误码-32602、-32601是 JSON-RPC 标准错误码。尚未实际运行本文未在真实 MCP 服务器上执行上述测试用例T1–T6 的“预期结果”是基于协议规范推导的读者需要在各自的实现上运行并核验。SDK v2 与 v1 在 API 层面的差异可能影响具体错误码的生成行为建议以你实际使用的 SDK 版本的文档为准。参考资料MCP Specification (2025-11-25): Tools. https://modelcontextprotocol.io/specification/2025-11-25/server/tools.md 核验日期2026-10-13MCP Specification (2025-06-18): Tools. https://modelcontextprotocol.io/specification/2025-06-18/server/tools.md 核验日期2026-10-13MCP Python SDK (v2). https://pypi.org/project/mcp/2.2.0/ 核验日期2026-10-13ErrorCode enum (mcp_dart). https://pub.dev/documentation/mcp_dart/2.4.1/mcp_dart/ErrorCode.html 核验日期2026-10-13