概述

MCP (Model Context Protocol) 使用 JSON-RPC 2.0 作为通信协议，定义了一套标准的错误码。本文提供完整的错误码参考和排查指南。

标准错误码

错误码	名称	说明
-32700	Parse error	JSON 解析失败
-32600	Invalid Request	无效的请求格式
-32601	Method not found	方法不存在
-32602	Invalid params	无效的参数
-32603	Internal error	内部错误

MCP 扩展错误码 (-32000 到 -32099)

错误码	名称	说明
-32000	Server error	MCP Server 内部错误
-32001	Connection error	连接错误
-32002	Timeout error	操作超时
-32003	Resource not found	资源不存在
-32004	Resource expired	资源已过期
-32005	Invalid resource	无效的资源

错误响应格式

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Invalid Request: missing method field",
    "data": {
      "details": "The 'method' field is required"
    }
  },
  "id": 1
}

常见错误排查

Parse Error (-32700)

import json

def send_request(method: str, params: dict = None):
    """发送 MCP 请求"""
    request = {
        "jsonrpc": "2.0",
        "method": method,
        "params": params or {},
        "id": generate_id()
    }
    
    try:
        json_str = json.dumps(request, ensure_ascii=False)
    except TypeError as e:
        raise ValueError(f"无法序列化请求: {e}")
    
    response = send_to_server(json_str)
    
    try:
        return json.loads(response)
    except json.JSONDecodeError as e:
        raise ValueError(f"服务器响应格式错误: {e}")

Invalid Params (-32602)

def validate_mcp_params(method: str, params: dict):
    """验证 MCP 参数"""
    # 定义每个方法的必需参数
    required_params = {
        "tools/list": [],
        "tools/call": ["name"],
        "resources/list": [],
        "resources/read": ["uri"]
    }
    
    required = required_params.get(method, [])
    missing = [p for p in required if p not in params]
    
    if missing:
        raise ValueError(
            f"Missing required params for {method}: {missing}"
        )
    
    return True

排查清单

1. 检查 JSON 格式：确保请求是有效的 JSON
2. 检查方法名：确认方法存在
3. 检查参数：验证参数类型和必填字段
4. 检查连接：确认 MCP Server 运行正常
5. 查看日志：检查 Server 端错误日志

参考资料

• MCP 协议规范
• JSON-RPC 2.0 规范