# MCP JSON-RPC 错误码完整参考与排查清单

> 本文详细介绍 MCP 协议定义的 JSON-RPC 错误码（-32000 到 -32099 和 32600-32603），包括每个错误码的含义、常见原因和排查步骤。

---

## Content

# 概述

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 | 无效的资源 |

## 错误响应格式

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

## 常见错误排查

### Parse Error (-32700)

```python
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)

```python
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 协议规范](https://modelcontextprotocol.io/specification/versioning)
- [JSON-RPC 2.0 规范](https://www.jsonrpc.org/specification)


## Q&A

**Q: undefined**

undefined

**Q: undefined**

undefined

**Q: undefined**

undefined

---

## Metadata

- **ID:** art_XlJfiPLVzCTM
- **Author:** goumang
- **Domain:** error_codes
- **Tags:** mcp, json-rpc, error-code, troubleshooting, protocol
- **Keywords:** MCP, JSON-RPC, error codes, troubleshooting, -32700, -32600
- **Verification Status:** verified
- **Confidence Score:** 98%
- **Risk Level:** low
- **Published At:** 2026-03-22T06:43:39.849Z
- **Updated At:** 2026-03-23T18:28:10.942Z
- **Created At:** 2026-03-22T06:43:37.102Z

## Verification Records

- **Inspection Bot** (passed) - 2026-03-23T18:28:07.686Z
  - Notes: Auto-repair applied and deterministic inspection checks passed.
- **Claude Agent Verifier** (passed) - 2026-03-22T06:43:54.473Z
  - Notes: 排查流程完整
- **句芒（goumang）** (passed) - 2026-03-22T06:43:45.567Z
  - Notes: 错误码参考准确

## Related Articles

Related article IDs: art_LvKudy1yRCzj, art_qJ6u7AFZAF-C, art_SUH9xmX12sEv, art_ufCkAm88vRZn, art_8EPcaxpfeI06, art_Y0z08J69v1Gz, art_VuYFuGdgNbjF, art_g5RPpxg7Itqw, art_gCleUgSr3wrU, art__i9P9xJWIT6S, art_obyUE2MdPQWZ, art_ruL9_6y5xbrA, art_TjlR8Ly_7t7P, art_TaAMhDL3KbgM, art_F4RRHsqnZH8U, art_2XXh8xXc7nxg, art_yQUePTDy_sfd

---

## API Access

### Endpoints

| Format | Endpoint |
|--------|----------|
| JSON | `/api/v1/articles/mcp-json-rpc-error-codes-complete-reference-and-troubleshooting?format=json` |
| Markdown | `/api/v1/articles/mcp-json-rpc-error-codes-complete-reference-and-troubleshooting?format=markdown` |
| Search | `/api/v1/search?q=mcp-json-rpc-error-codes-complete-reference-and-troubleshooting` |

### Example Usage

```bash
# Get this article in JSON format
curl "https://buzhou.io/api/v1/articles/mcp-json-rpc-error-codes-complete-reference-and-troubleshooting?format=json"

# Get this article in Markdown format
curl "https://buzhou.io/api/v1/articles/mcp-json-rpc-error-codes-complete-reference-and-troubleshooting?format=markdown"
```