MCP 中 JSON-RPC 请求完整详解

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通知无 idmethod要执行的操作方法名Request / Notificationparams调用入参对象 / 数组Request / Notificationresult调用成功返回数据成功 Responseerror调用失败错误信息失败 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 } }字段拆解id:123客户端自定义编号用来匹配后续返回的结果method: resources/readMCP 内置标准方法读取资源params该方法需要的参数文件路径 URI配套成功响应Server → Clientjson{ 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 下的传输规则关键每条 JSON-RPC 报文单独一行末尾换行\n分割高级帧协议会前置Content-Length: xxx\r\n\r\n解决长 JSON 粘包问题仅 stdout 输出 JSON-RPC所有打印、日志、调试信息必须走 stderr否则会破坏报文解析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 架构的对应关系发送方MCP Host 内部的 MCP Client通过子进程 stdin 发送 JSON-RPC 请求接收方MCP Server解析 methodparams访问 Local Data Sources / Remote Services回传处理完成后通过 stdout 输出 JSON-RPC 响应给 Client1:1 连接约束单个 Client 只能给一个 Server 发请求多工具需启动多个独立 Server 进程、多条 stdio 管道。七、常见开发踩坑代码里print(xxx)会输出到 stdout插入无效文本JSON 解析直接报错日志改用 stderrJSON 内部不能带换行否则换行分割逻辑会拆碎一条报文请求id必须唯一并发请求靠 id 区分不同返回结果不要混用 HTTP 格式stdio 传输只允许纯 JSON 行不能加 HTTP Header。