MCP 中 JSON-RPC 请求完整详解

MCP 底层通信完全基于 JSON-RPC 2.0 规范，所有 stdio 传输的消息都遵循这套格式，分为三类：请求 Request、响应 Response、通知 Notification。

一、JSON-RPC 2.0 标准基础字段

所有报文第一行固定 jsonrpc: "2.0"，代表协议版本：

表格

字段	含义	适用消息
jsonrpc	协议版本，固定 "2.0"	全部消息
id	请求唯一标识，数字 / 字符串；响应会原样带回	Request / Response（通知无 id）
method	要执行的操作方法名	Request / Notification
params	调用入参，对象 / 数组	Request / Notification
result	调用成功返回数据	成功 Response
error	调用失败错误信息	失败 Response

二、标准 JSON-RPC 请求（Request）

由 MCP Client（宿主程序）发给 MCP Server，必须带 id，服务端必须返回对应响应。

最简示例：读取本地文件（MCP 典型请求）

json

{
  "jsonrpc": "2.0",
  "id": 123,
  "method": "resources/read",
  "params": {
    "uri": "file:///C:/test.txt"
  }
}

字段拆解：

1. id:123：客户端自定义编号，用来匹配后续返回的结果
2. method: "resources/read"：MCP 内置标准方法，读取资源
3. params：该方法需要的参数，文件路径 URI

配套成功响应（Server → Client）

json

{
  "jsonrpc": "2.0",
  "id": 123,
  "result": {
    "content": "文件里的文本内容..."
  }
}

错误响应（文件不存在示例）

json

{
  "jsonrpc": "2.0",
  "id": 123,
  "error": {
    "code": -32001,
    "message": "File not found",
    "data": "file:///C:/test.txt"
  }
}

三、JSON-RPC 通知（Notification，特殊无 ID 请求）

不带 id，服务端不需要回复，多用于日志、状态推送：

json

{
  "jsonrpc": "2.0",
  "method": "logging/message",
  "params": {
    "level": "info",
    "message": "开始扫描本地文件夹"
  }
}

四、MCP 在 stdio 下的传输规则（关键）

1. 每条 JSON-RPC 报文单独一行，末尾换行 \n 分割；
2. 高级帧协议会前置 Content-Length: xxx\r\n\r\n 解决长 JSON 粘包问题；
3. 仅 stdout 输出 JSON-RPC，所有打印、日志、调试信息必须走 stderr，否则会破坏报文解析；
4. Client ↔ Server 是 1:1 管道，所有请求、响应串行收发。

五、MCP 常用标准 JSON-RPC Method（请求方法）

1. 初始化握手（连接建立第一条请求）

json

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "initialize",
  "params": {
    "protocolVersion": "0.1.0",
    "clientInfo": {
      "name": "claude-desktop",
      "version": "0.7.0"
    }
  }
}

作用：Client 和 Server 协商协议版本、交换客户端信息。

2. 获取服务端能力列表（列出工具 / 资源）

json

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

Server 返回自身提供的所有可用工具（读文件、查数据库等）。

3. 调用工具（AI 最常用）

json

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "list_directory",
    "arguments": {
      "path": "./docs"
    }
  }
}

六、和 MCP 架构的对应关系

1. 发送方：MCP Host 内部的 MCP Client，通过子进程 stdin 发送 JSON-RPC 请求；
2. 接收方：MCP Server，解析 method+params，访问 Local Data Sources / Remote Services；
3. 回传：处理完成后，通过 stdout 输出 JSON-RPC 响应给 Client；
4. 1:1 连接约束：单个 Client 只能给一个 Server 发请求，多工具需启动多个独立 Server 进程、多条 stdio 管道。

七、常见开发踩坑

1. 代码里 print("xxx") 会输出到 stdout，插入无效文本，JSON 解析直接报错；日志改用 stderr；
2. JSON 内部不能带换行，否则换行分割逻辑会拆碎一条报文；
3. 请求 id 必须唯一，并发请求靠 id 区分不同返回结果；
4. 不要混用 HTTP 格式，stdio 传输只允许纯 JSON 行，不能加 HTTP Header。