当 AI Agent 通过 MCP（Model Context Protocol）调用数据库、搜索、文件系统或业务 API 时，失败并不只是“返回一条错误消息”那么简单。错误究竟发生在协议传输、参数校验、权限控制，还是工具执行阶段，将直接影响客户端能否重试、模型能否自我修正，以及运维系统能否快速定位问题。🧭 因此，一套可靠的 MCP 工具调用体系，应同时设计协议错误、工具错误、结构化业务错误和异常治理策略。
一、先区分协议错误与工具执行错误
MCP 消息以 JSON-RPC 2.0 为基础。协议层错误表示请求本身无法被正常处理，例如 JSON 无法解析、方法不存在或参数格式不合法。此时应返回 JSON-RPC 的 error 对象，其中包含 code、message，并可通过 data 携带诊断信息。常见标准错误码包括：-32700 解析错误、-32600 无效请求、-32601 方法不存在、-32602 参数无效以及 -32603 内部错误，具体定义可参考 来源链接 2.0 规范。
工具执行错误则不同：tools/call 请求已经被协议层正确接收，但实际业务操作没有完成。例如查询条件没有结果、库存不足、第三方服务暂时不可用。按照 MCP 的工具结果设计，这类失败通常应返回正常的 result，并设置 isError=true，让模型能够读取 content 中的说明并决定是否修正参数、改用其他工具或向用户补充提问。相关机制可参阅 MCP 工具规范。
判断原则：如果客户端或模型仍有机会调整调用并继续任务，优先使用工具执行错误；如果请求连协议处理阶段都无法通过，则使用 JSON-RPC 协议错误。
二、建立分层异常分类体系
错误码不宜按具体接口随意增长，而应先建立稳定的分类维度。推荐将 MCP 工具调用异常划分为以下六类：
- PROTO：协议与消息格式异常，如 JSON 损坏、请求字段缺失、方法名称错误。
- VALIDATION：参数校验异常，如必填字段缺失、类型不匹配、数值越界或格式不符合 inputSchema。
- AUTH：身份与权限异常，如凭证失效、授权范围不足、用户拒绝高风险操作。
- RESOURCE：资源状态异常，如文件不存在、记录已删除、版本冲突或资源被锁定。
- DEPENDENCY：外部依赖异常，如下游 API 超时、数据库连接失败、限流或服务不可用。
- INTERNAL：服务内部异常，如未捕获异常、配置缺失、序列化失败或程序状态不一致。
这种分类方式能够把“谁应处理错误”表达清楚：VALIDATION 通常由模型修改参数，AUTH 可能需要用户重新授权，DEPENDENCY 可交给重试与熔断机制，而 INTERNAL 则应触发服务端告警。🔧
三、设计稳定的结构化错误对象
面向模型返回的错误不能只有一句“调用失败”。建议在工具结果的文本之外，通过 structuredContent 或受控的 JSON 字段提供机器可读信息。一个实用的错误对象可包含以下内容：
- errorCode：稳定的业务错误码，例如 DEPENDENCY.TIMEOUT。
- category：错误类别，用于路由重试、授权或人工处理流程。
- message：适合用户或模型阅读的简短说明。
- retryable：是否允许自动重试，避免模型盲目重复调用。
- retryAfterMs：建议等待时间，仅在服务端能够合理判断时提供。
- fieldErrors：字段级校验结果，指出参数路径、问题和修正提示。
- requestId：跨客户端、MCP Server 与下游服务追踪调用链的标识。
- details：经过脱敏的补充上下文，不应包含令牌、密码或内部堆栈。
错误码应保持稳定，message 可以迭代优化。客户端逻辑必须依据 errorCode 和 category 作出判断，而不是匹配自然语言文本。为避免命名混乱，可以采用“领域.原因”的形式，例如 VALIDATION.MISSING_FIELD、AUTH.SCOPE_DENIED、RESOURCE.NOT_FOUND、DEPENDENCY.RATE_LIMITED。
四、明确可重试与不可重试边界
自动重试并不适用于所有异常。网络抖动、临时超时、下游 5xx 或明确的限流响应通常可以重试，但应配合指数退避、随机抖动和最大次数限制。参数错误、权限不足、资源不存在等问题在条件未改变前不应重试，否则只会增加负载并制造重复日志。⏱️
对于具有副作用的工具，例如付款、发信、删除文件或创建工单，还必须引入幂等键。即使客户端因为超时没有收到结果，也不能直接假定操作失败并重复执行。服务端应根据幂等键识别重复请求，并返回原操作结果或当前状态。
五、处理安全信息与模型可见内容
MCP 错误需要同时服务于模型、用户和运维人员，但三者不应看到完全相同的信息。模型可见内容应说明失败原因和下一步动作；用户可见内容应简洁、可理解；详细堆栈、SQL 语句、文件绝对路径和下游响应正文则应保留在受控日志中。🔐
建议对错误信息进行分级：公开层返回安全描述与 requestId，诊断层记录异常类型、调用耗时和依赖状态，敏感层仅在严格权限控制下保存必要数据。日志还应进行令牌、Cookie、个人信息及业务机密脱敏，避免错误处理本身成为数据泄露入口。
六、统一客户端处置策略
客户端收到错误后，可按固定顺序决策：
- 先判断是 JSON-RPC error，还是带有 isError=true 的工具结果。
- 读取 category、errorCode 与 retryable，不依赖 message 文案匹配。
- 参数问题由模型修正，但应限制连续自我修正次数。
- 授权问题提示用户完成授权或拒绝操作，不自动扩大权限。
- 可重试异常执行退避策略，并保留同一条调用链标识。
- 不可恢复异常停止工具循环，向用户说明影响和可选方案。
此外，还要防止“调用—失败—重试”的无限循环。客户端可以按照工具名、参数摘要和错误码识别重复失败；当相同组合连续出现时，应终止自动调用并转入人工确认或降级路径。
七、测试与可观测性不可缺位
结构化错误设计完成后，应通过契约测试验证每个工具的参数错误、权限异常、超时、限流、资源冲突和内部异常。测试重点不仅是错误码是否正确，还包括 isError 是否合理、敏感信息是否泄露、重试标记是否准确，以及模型能否依据提示采取有效行动。🧪
监控指标可围绕错误类别占比、工具失败率、重试成功率、平均恢复时间和重复调用次数展开。requestId 应贯穿 MCP 客户端、Server 和下游系统，使一次失败能够被完整还原，而不是散落在多个互不关联的日志文件中。
总结
优秀的 MCP 错误体系，不是错误码越多越好，而是能够准确回答三个问题：错误发生在哪一层、谁可以处理、下一步应该做什么。通过区分协议错误与工具执行错误，建立分层分类、稳定错误码、可重试语义、脱敏机制和统一客户端策略，AI Agent 才能从“遇错即停”升级为可诊断、可恢复且可治理的可靠系统。✅
