【随笔】MCP工具错误怎样分层：先读反馈，再决定下一步

上一篇给MCP工具结果加上结构与业务检查。接着沿调用链想一层工具没有给出可用结果时Agent应该修改参数、等待更多输入还是先停止操作把所有失败都写成“再试一次”会丢掉关键线索。今天整理MCP工具错误的分层表达。我们用几份模拟响应观察客户端怎样分流让模型收到可以处理的反馈同时保留系统对执行边界的判断。本文依据2026年10月6日核对的MCP2026-07-28规范。示例使用Python3.12.14在本地实际运行只演示应用处理策略不连接真实MCP服务器不代表某个SDK的完整实现。一、失败发生在哪一层MCP工具规范区分两种错误协议错误用JSON-RPC的error响应表达工具执行错误在结果中设置isError: true。未知工具、请求结构问题与工具执行中的校验、API或业务错误需要分别识别。官方工具错误处理在这两种服务器反馈之外客户端也可能遇到本地超时。这时甚至没有收到响应应保留“结果未知”的状态。下图把可观察到的线索放在不同入口便于后续处理。图中超时属于本地观察结果不能冒充服务器返回的JSON-RPC错误。收到error或isError之后仍需结合具体反馈判断操作是否留下影响。二、协议错误先检查请求与接口下面展示一份未知工具的错误响应与官方示例使用相同错误码{jsonrpc:2.0,id:1,error:{code:-32602,message:Unknown tool: missing_tool}}JSON-RPC响应的error包含整数code与message可有data携带额外信息。MCP还对标准错误码和部分服务器错误码范围作了约定本地实现的超时目前没有被统一分配协议错误码。基础协议与错误码应用层可以核对工具目录、参数结构和协商版本。遇到未知工具时原样重复同一请求通常不会得到新结果。错误码也不宜单独充当重试开关需要结合接口说明与具体故障。三、工具执行错误把可修正的信息交给Agent工具已进入执行过程发现日期无效时可以给出下面的结果片段{jsonrpc:2.0,id:2,result:{resultType:complete,isError:true,content:[{type:text,text:Date must be in the future}]}}resultType为complete表示请求已经给出最终内容是否工具执行失败仍要读取isError。当前版本还可能返回input_required早期版本缺少resultType时按complete处理未识别的结果种类应视为无效。结果种类说明规范建议客户端把工具执行错误提供给模型使其能够根据反馈修正。应用设计上可以提供简短原因和允许的输入范围数据库连接串、访问令牌或完整内部堆栈没有必要作为模型反馈公开。图中反馈先经过应用判断才进入下一次请求。修正日期的请求表达新的意图它与超时后原样重放同一次写入应分别处理。四、完整示例六类观察怎样分流为了只观察分层规则下面省略网络与SDK接入。kind是本地程序自行定义的事件字段协议响应放在response里函数假设响应基本结构已通过前置校验。输出是处理建议不会自动调用工具。defdecide(event):# Local illustrative policy: no network calls and no automatic retries.ifevent[kind]timeout:returnOUTCOME_UNKNOWN: query status firstresponseevent[response]iferrorinresponse:returnPROTOCOL_ERROR: inspect request and serverresultresponse[result]result_typeresult.get(resultType,complete)ifresult_typeinput_required:returnINPUT_REQUIRED: use the negotiated input flowifresult_type!complete:returnINVALID_RESULT: stopifresult.get(isError,False):returnTOOL_ERROR: inspect actionable feedbackreturnRESULT_READY: validate structure and business statecases[(protocol,{kind:response,response:{jsonrpc:2.0,id:1,error:{code:-32602,message:Unknown tool: missing_tool}}}),(tool,{kind:response,response:{jsonrpc:2.0,id:2,result:{resultType:complete,isError:True,content:[{type:text,text:Date must be in the future}]}}}),(ready,{kind:response,response:{jsonrpc:2.0,id:3,result:{resultType:complete,isError:False,content:[{type:text,text:Report prepared}]}}}),(input,{kind:response,response:{jsonrpc:2.0,id:4,result:{resultType:input_required,inputRequests:{details:{method:elicitation/create,params:{mode:form,message:Provide details,requestedSchema:{type:object}}}}}}}),(unknown_type,{kind:response,response:{jsonrpc:2.0,id:5,result:{resultType:not_negotiated}}}),(timeout,{kind:timeout}),]forname,eventincases:print(f{name}:{decide(event)})保存为error_layers_demo.py并执行python error_layers_demo.py本次实际输出protocol: PROTOCOL_ERROR: inspect request and server tool: TOOL_ERROR: inspect actionable feedback ready: RESULT_READY: validate structure and business state input: INPUT_REQUIRED: use the negotiated input flow unknown_type: INVALID_RESULT: stop timeout: OUTCOME_UNKNOWN: query status firstready只进入后续结构与业务检查尚未宣告业务完成。input交给已协商的补充输入流程unknown_type停止。timeout也停止自动推进先查询状态。这样的分流让每一次失败保留自己的处理入口。五、恢复决策怎样留下边界可观察线索应用可以先做什么需要另行确认什么JSON-RPC error检查请求、工具定义与服务端反馈接口是否支持恢复isError为true提取可修正原因并校验新参数是否已经发生部分副作用input_required进入协商过的补充输入流程输入来源与用户意图本地超时回查状态或停止推进服务端是否已经执行普通完整结果继续结构与业务核验结果是否满足下一步条件重试是应用策略。设置次数预算、整体时限与退避规则是恢复流程的一部分这些条件不能保证写入只发生一次。涉及状态变化时应依据工具契约判断幂等性与回查能力上一篇讲过的结果校验也要保留。错误反馈不等于回滚证明。下游API失败前可能已有部分动作完成。工具若能返回任务编号、明确阶段或可查询状态调用端更容易给出可解释的处理结果这些业务字段要由工具契约定义。注解需要可信来源。工具的行为注解可以帮助理解接口但客户端仍需校验来源与结果。将readOnlyHint或idempotentHint当成某个不可信服务自动获得执行权限的依据会让应用判断失去约束。六、落地时补上这些检查将协议解析、结果分流、业务校验与执行授权分别放在明确入口日志保存关联ID与决策原因避免把秘密参数完整写进日志。给模型的反馈尽量清楚哪个字段需要调整、允许范围是什么、哪些条件还没确认。下一次调用仍需经过参数校验不能仅凭模型说“已修复”就直接执行。生产接入还要校验响应结构、请求ID关联、协议协商结果和错误内容可信度。本文六个用例没有覆盖断线、所有标准错误码或真实服务器恢复行为不能替代联机验证。七、 思维导图MCP工具错误协议层JSON-RPC error执行层isError反馈本地观察超时保留结果未知结果分流complete与input_required恢复策略校验参数和副作用边界八、总结总结要点先识别错误层次。协议error、工具isError与本地超时提供不同线索客户端应该保留这些差异。反馈服务于下一步判断。可修正的信息能帮助Agent调整输入新的调用仍需校验与授权。恢复遵守工具契约。收到失败或没有响应都不能直接推导回滚已经完成结果核验、状态回查和副作用处理要一起设计。下一篇继续看MCP工具注解理解readOnlyHint与idempotentHint能提示什么以及调用端怎样判断可信度。如果你觉得这篇文章对你有所帮助欢迎点赞、收藏、分享