#MCP 协议知识分享#

🛠 MCP 错误码体系与问题排查实战

——给 AI 工程师的一份真实 Debug 生存指南

---

🧠 一、为什么 MCP 错误码值得单独讲一篇？

你可能觉得：“错误码不就是 400、500、401 吗？”

不。MCP 的错误码设计，就像是协议的“自我说明书”+“自愈机制”。

• 它是 接口的最后一道防线，能准确告诉你是调用方的问题，还是服务方的问题；
• 它是 排查的起点，帮你区分“哪一层出错了”（网关？模型？业务逻辑？资源池？）；
• 它还能 引导开发者自我恢复（提示重试、补参、改权限）。

没有结构化的错误码，你会陷入：

“模型调用失败了，请联系管理员” 🤷

---

📊 二、MCP 错误码分类体系（推荐结构）

我们建议 MCP 错误码体系采用类似 HTTP 状态码的 5 段式设计，但更细分、更语义化：

错误段	范围	类型	示例
10000 ~19999	客户端参数类	缺参、格式错	10001 参数缺失
20000~29999	鉴权权限类	Token 失效、权限不足	20003 权限拒绝
30000~39999	模型服务类	模型超时、资源不足	30007 模型不可用
40000~49999	插件/中间件	插件执行异常	40005 插件加载失败
50000+	系统级别	内部异常、不可预期	50001 内部错误

---

🧪 三、常见错误码实战解析

1. 10002 参数格式错误

日志提示：

{
  "traceId": "abc-123",
  "code": 10002,
  "msg": "字段 temperature 期望为 float，但传入了 string"
}

定位方式：

• traceId 定位请求链
• 请求体反序列化失败 → 检查 SDK 参数定义

2. 20004 Token 无效或过期

• 通常是调用方没带 token、token 过期或签名串非法

排查建议：

• 检查 Header 是否包含 X-Token
• 如果使用 JWT，查看是否过期 / 被吊销

---

🔍 四、MCP 错误处理流程图（标准处理逻辑）

---

⚙️ 五、Java 示例：错误码定义与使用

错误码定义枚举

public enum McpErrorCode {
    PARAM_MISSING(10001, "参数缺失"),
    TOKEN_EXPIRED(20004, "Token 已过期"),
    MODEL_TIMEOUT(30001, "模型响应超时"),
    PLUGIN_ERROR(40003, "插件处理异常"),
    INTERNAL_ERROR(50001, "系统异常");

    private final int code;
    private final String message;

    McpErrorCode(int code, String message) {
        this.code = code;
        this.message = message;
    }
}

抛出标准异常

if (!request.containsKey("prompt")) {
    throw new McpException(McpErrorCode.PARAM_MISSING);
}

---

🧩 六、如何设计一个“能自我修复”的错误返回？

错误不仅要提示“哪里错了”，还要建议“怎么修”。

优化版响应：

{
  "code": 20003,
  "msg": "调用者权限不足，模型需权限等级：level-3",
  "solution": "请申请模型权限或更换模型",
  "traceId": "abc-xyz-123"
}

这种结构对前端、网关、开发者都极其友好，甚至可以用于自动重试、灰度降级。

---

🔐 七、常见排查技巧（来自一线工程师）

场景	建议做法
响应 500，且无详细错误码	检查日志是否丢失 traceId，优先补日志结构
多次请求都失败	使用 traceId + spanId 排查路径中哪个环节异常
模型服务频繁返回 30007	排查资源池是否负载过高，是否限流配置缺失
插件处理失败（400xx）	插件是否热更失败？是否类冲突/依赖缺失？

---

🧠 八、小结：错误码不是报错工具，是 Debug 导航仪

• 错误码要足够结构化、语义化、可扩展；
• 建议统一封装 SDK，避免业务代码硬编码魔法数字；
• 所有错误码都应配文档，甚至写入 Swagger/OpenAPI；
• traceId + 错误码 = 最强 Debug 双人组；
• 好的错误码体系，能让调用方自愈、不打扰。

---

📎 下一篇预告：

Debug 结束了，回到设计阶段。我们进入 MCP 最终章——

👉 《AI 调度网关中的 MCP 策略引擎设计》