1. 项目概述为什么我们需要拆解 MCP 协议最近在搞 AI Agent 开发的朋友估计没少听到 MCP 这个词。它就像 Agent 世界里的“通用插头”让不同的工具、数据源和 AI 模型能顺畅对话。但说实话很多教程和文档都停留在“怎么用”的层面比如告诉你装个 MCP Server在 Cursor 里配一下就能连数据库了。这当然有用可一旦出点岔子或者你想自己从头搭一个定制化的 Agent 工具链就会一头雾水消息到底是怎么传的为什么我的请求超时了这个协议底层到底长啥样这就是我想写这个系列的原因。市面上讲 AI Agent 架构、讲应用案例的内容很多但把底层通信协议——尤其是 MCPModel Context Protocol——掰开揉碎了讲的还真不多见。很多人把它当成一个黑盒只知道它能“连接”却不清楚连接背后的“语言”和“交通规则”。这期我们就从最基础的“消息格式”和“传输层”入手把 MCP 协议彻底拆解明白。无论你是想深度定制 Agent 能力还是仅仅为了在调试时心里有底理解这些底层细节都至关重要。简单说MCP 定义了一套 AI 应用比如 Claude Desktop、Cursor与外部资源工具、数据库、API 等之间进行通信的标准方式。你可以把它想象成 HTTP 之于 Web或者 gRPC 之于微服务。但它的消息设计更贴近 AI 的“思考”模式比如工具调用、上下文读取等。搞懂它你就能真正理解 AI Agent 是如何“伸手”去操作外部世界的而不仅仅是调用一个封装好的 SDK。2. MCP 协议的核心设计哲学与消息格式2.1 协议定位不是 RPC而是资源会话协议首先得澄清一个常见的误解。很多人一看到“协议”和“消息”就下意识地把它归类为像 gRPC 或 JSON-RPC 那样的远程过程调用RPC协议。虽然 MCP 在形式上确实有请求和响应但其设计哲学有根本不同。RPC 的核心是“调用一个函数并获取结果”是命令式的。而 MCP 的核心思想是“声明资源并管理会话”是声明式的。它的目标不是让客户端直接“命令”服务器做什么而是建立一个共享的“上下文Context”会话。在这个会话中服务器向客户端“宣告”自己有哪些资源比如可用的工具、可读取的文件列表客户端则根据 AI 模型的需要来“订阅”或“使用”这些资源。这个区别体现在消息结构上。一个典型的 MCP 会话始于服务器发送initialize请求紧接着是一系列notifications来宣告资源如tools/listresources/list。之后客户端通过requests如tools/call来使用资源服务器用responses回复。整个流程更像是在建立一个动态的、可供查询的“资源目录”而不是简单的函数调用链。理解这一点是看懂后续所有消息格式的基础。2.2 消息信封Envelope所有通信的通用包装无论什么内容在 MCP 中传输时都会被装进一个标准的“信封”里。这个信封结构是协议稳定性的基石。一个完整的 MCP 消息信封通常包含以下字段{ jsonrpc: 2.0, id: unique-request-id-123, method: tools/call, params: { ... }, result: { ... }, error: { ... } }我们来逐一拆解jsonrpc: 固定为2.0。这表明 MCP 在消息层兼容 JSON-RPC 2.0 规范。这是一个非常明智的选择直接复用了一个成熟、广泛支持的协议标准避免了重复发明轮子也让开发者能利用现有的 JSON-RPC 客户端/服务器库进行调试和开发。id: 请求的唯一标识符。用于匹配请求和响应这是实现异步通信的关键。客户端生成服务器在对应的响应中原样返回。如果消息是通知Notification则没有id字段。method: 指示消息的类型或意图。它采用类似路径的命名方式如tools/list,resources/read清晰地区分了不同的功能模块。这是理解消息含义的钥匙。params: 仅存在于请求Request中包含了执行该method所需的具体参数。例如tools/call的params里就会包含工具名称和调用参数。result: 仅存在于成功的响应Response中包含了请求执行的结果。error: 仅存在于失败的响应中遵循 JSON-RPC 2.0 的错误对象格式包含code,message和可选的data字段用于精确传递错误信息。注意一个消息信封中result和error是互斥的params和result/error也是互斥的。这保证了消息语义的清晰。2.3 核心消息类型详解初始化、工具与资源了解了通用信封我们来看几种最核心的消息类型它们构成了 MCP 会话的骨架。2.3.1 初始化握手 (initializeinitialized)任何 MCP 会话都始于一个握手过程。客户端首先发送initialize请求{ jsonrpc: 2.0, id: 1, method: initialize, params: { protocolVersion: 2024-11-05, capabilities: { roots: { listChanged: true }, tools: { listChanged: true } }, clientInfo: { name: Claude Desktop, version: 1.0.0 } } }这里protocolVersion指明了客户端兼容的协议版本capabilities声明了客户端支持哪些特性例如是否希望接收资源列表变更的通知。服务器响应result其中包含服务器的信息及其支持的能力。随后客户端发送一个initialized通知握手完成会话进入就绪状态。2.3.2 工具声明与调用 (tools/list,tools/call)“工具”是 MCP 中最核心的概念之一它让 AI 能够执行具体操作如运行代码、查询数据库。列表声明 (tools/list)服务器通过通知或响应向客户端宣告可用工具列表。每个工具的定义类似于 OpenAPI 的 Function Calling包含name,description,inputSchemaJSON Schema 格式等。关键在于这是一个动态列表服务器可以在会话中随时发送tools/list通知来更新工具集客户端需要监听这种变化。调用执行 (tools/call)当 AI 决定使用某个工具时客户端发送tools/call请求。params中包含了name和arguments。服务器执行后在result中返回执行结果。这个结果通常是一个结构化的content数组可以包含文本、图像甚至代码片段。2.3.3 资源读取与订阅 (resources/list,resources/read)“资源”代表了服务器提供的静态或动态内容比如文件系统的目录、数据库的表结构描述、API 的文档等。AI 可以读取这些资源作为上下文但不直接修改它们。列表声明 (resources/list)与工具类似服务器宣告可用的资源列表。每个资源有uri如file:///path/to/doc.md和mimeType等元数据。内容读取 (resources/read)客户端通过resources/read请求指定资源的uri服务器返回其内容。这为 AI 提供了强大的上下文注入能力。例如一个连接代码库的 MCP 服务器可以将相关源代码文件作为资源提供给 AI 参考。变更订阅如果客户端在初始化时声明了roots.listChanged能力那么当服务器监控的资源根目录列表发生变化时例如新增了一个 Git 仓库它会发送notifications/root通知客户端随后可以重新获取resources/list。2.4 消息流与状态管理理解了单个消息我们再把它们串起来看一个典型的会话流程连接建立传输层连接如 STDIO、SSE建立。初始化客户端 -initialize- 服务器 -initialize响应 - 客户端 -initialized通知。资源/工具宣告服务器 -tools/list通知 resources/list通知。此时客户端侧的 AI 应用界面中工具列表和可用资源就应该显示出来了。会话交互AI 用户提问。AI 模型在客户端分析后可能决定调用一个工具客户端 -tools/call。服务器执行并返回结果。AI 模型也可能需要读取某个资源作为参考客户端 -resources/read。服务器返回资源内容。此过程循环往复。动态更新在会话中如果服务器背后的工具或资源发生变化例如监测到文件变动它会主动发送tools/list或notifications/root通知客户端同步更新状态。连接关闭传输层连接断开会话结束。这个流程体现了 MCP 的“会话”特性状态是动态维护的通信是双向的服务器可以主动推送通知而非简单的“一问一答”。3. 传输层实现消息如何被搬运协议规定了“说什么”传输层则解决“怎么送”。MCP 设计上支持多种传输方式这赋予了它极大的部署灵活性。3.1 标准输入输出最简单直接的本地通信这是开发调试和本地集成中最常用的方式。MCP Server 作为一个独立的进程启动通过标准输入stdin接收消息通过标准输出stdout发送消息。客户端如 Claude Desktop则启动这个进程并管理其生命周期。工作原理客户端启动服务器进程并建立了到该进程 stdin/stdout 的管道。双方约定每条消息以换行符\n分隔。发送方将 JSON 格式的消息字符串后加上\n写入自己的输出流。接收方持续读取输入流按\n分割得到完整的 JSON 字符串进行解析。实操要点与避坑指南缓冲与刷新这是最容易出问题的地方。在写入 stdout 后必须立即执行刷新操作如在 Node.js 中用console.log会自动刷新或手动process.stdout.flush()在 Python 中用sys.stdout.flush()。否则消息可能会留在缓冲区导致对方无法及时收到造成通信死锁。错误流分离stderr 通常用于输出日志和错误信息而非协议消息。客户端需要同时监听 stderr 来获取服务器的调试输出这有助于排查问题。进程生命周期管理客户端需要妥善处理服务器进程的崩溃、无响应和正常退出。通常需要设置超时机制并在进程异常退出时清理资源、通知用户。个人踩坑实录早期写一个 Python MCP Server 时我用print(json.dumps(msg))发送消息但在一个长时间运行的工具调用后AI 端迟迟收不到响应。排查了半天发现是输出被缓冲了。在print后加上sys.stdout.flush()立即解决。所以记住“写完就刷”是 STDIO 传输的金科玉律。3.2 服务器发送事件更适合 Web 环境的流式传输SSE 是一种基于 HTTP 的服务器向客户端推送数据的技术。在 MCP 中它通常用于服务器部署在远程客户端通过 HTTP 访问的场景。工作原理客户端向服务器的特定端点如https://mcp-server.example.com/sse发起一个 HTTP GET 请求。服务器保持这个连接打开并以text/event-stream格式持续发送事件。每个 MCP 消息被包装成一个 SSE 事件event: message数据部分data:就是 JSON 字符串化的消息。客户端通过 EventSource API 监听这些事件并解析。消息格式示例event: message data: {jsonrpc:2.0,id:1,method:tools/list,params:{...}} event: message data: {jsonrpc:2.0,id:1,result:{...}}优势与挑战优势基于 HTTP穿透性好适合浏览器环境或跨网络通信。天然支持服务器向客户端的单向实时推送对应 MCP 的通知。挑战SSE 是单向的服务器-客户端。为了支持客户端向服务器发送请求如tools/call需要另一个通信通道通常是额外的 HTTP POST 端点。这增加了实现的复杂性需要维护两个连接和关联状态。3.3 其他传输方式与选择考量除了上述两种理论上 MCP 可以通过任何双向字节流传输例如WebSocket真正的全双工通信比 SSEPOST 的组合更优雅是构建复杂、交互式 Web MCP 客户端的理想选择。TCP Socket在本地或网络环境中提供更底层的控制性能可能更高但需要自己处理连接管理、心跳等细节。传输层选型决策表传输方式适用场景优点缺点实现复杂度STDIO本地集成、CLI工具、桌面应用简单、无需网络、进程隔离好仅限本地、需管理进程生命周期低SSE HTTP POST远程服务器、Web前端集成基于HTTP、穿透性强、支持服务器推送双向通信需两个通道、实现稍复杂中WebSocket实时性要求高的Web应用全双工、单一连接、高效需要WebSocket服务器、连接状态管理中高TCP Socket高性能内部服务间通信低延迟、高吞吐量最复杂、需处理所有网络层细节高对于绝大多数 AI 集成场景如 IDE 插件、桌面 AI 助手STDIO 是最推荐、最稳定的方式。它部署简单安全性相对好进程沙盒且被所有主流 MCP 客户端Cursor, Claude Desktop, Windsurf原生支持。只有在明确需要远程访问或浏览器内集成的需求时才考虑 SSE 或 WebSocket。4. 实战从零实现一个简单的 MCP Server理解了理论和格式最好的巩固方式就是动手。让我们用 Node.js 实现一个最简单的 MCP Server它提供一个查询当前时间的工具。我们将使用官方的modelcontextprotocol/sdk来简化开发。4.1 环境准备与项目初始化首先确保你安装了 Node.js版本 18。然后创建一个新目录并初始化项目mkdir mcp-time-server cd mcp-time-server npm init -y安装 MCP SDKnpm install modelcontextprotocol/sdk4.2 服务器核心代码实现创建一个server.js文件写入以下代码const { Server } require(modelcontextprotocol/sdk/server/index.js); const { StdioServerTransport } require(modelcontextprotocol/sdk/server/stdio.js); // 1. 创建 Server 实例 const server new Server( { name: mcp-time-server, version: 0.1.0, }, { capabilities: { tools: {}, // 声明本服务器提供工具 }, } ); // 2. 定义工具获取当前时间 server.setRequestHandler(tools/list, async () { return { tools: [ { name: get_current_time, description: 获取当前的系统日期和时间, inputSchema: { type: object, properties: { // 这个工具不需要参数所以 properties 为空对象 }, // 不允许传入任何未定义的参数 additionalProperties: false, }, }, ], }; }); // 3. 处理工具调用请求 server.setRequestHandler(tools/call, async (request) { const { name, arguments: args } request.params; if (name ! get_current_time) { throw new Error(未知的工具: ${name}); } // 实际执行工具逻辑 const now new Date(); const timeString now.toLocaleString(zh-CN, { timeZone: Asia/Shanghai, hour12: false, }); return { content: [ { type: text, text: 当前系统时间是${timeString}, }, ], }; }); // 4. 启动服务器使用 STDIO 传输 async function main() { const transport new StdioServerTransport(); await server.connect(transport); console.error(MCP 时间服务器已启动通过 STDIO 通信。); } main().catch((error) { console.error(服务器启动失败:, error); process.exit(1); });代码关键点解析Server 实例化需要提供服务器元信息和能力声明。这里我们只声明了tools能力。工具列表声明在tools/list处理器中返回一个工具数组。每个工具必须定义清晰的name,description和inputSchema。inputSchema使用 JSON Schema 定义参数这对于 AI 模型安全、正确地调用工具至关重要。工具调用处理在tools/call处理器中根据request.params.name识别要调用的工具执行逻辑并返回格式化的结果。结果必须包裹在content数组中这是 MCP 协议要求的格式。传输层绑定使用StdioServerTransport()创建标准输入输出传输器并用server.connect()绑定。之后所有协议通信将通过进程的 stdin/stdout 进行。4.3 测试与调试你的服务器编写完成后我们可以直接运行它并手动模拟客户端发送消息来测试。首先运行服务器node server.js此时服务器会阻塞等待 stdin 的输入。在另一个终端我们可以用echo命令模拟客户端发送初始化请求# 注意每条消息必须是一个完整的 JSON并以换行符 \n 结尾。 echo {jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:Test Client,version:1.0}}} | node server.js但这不太方便观察。更好的方法是使用一个简单的测试脚本或者使用现有的 MCP 客户端进行集成测试。使用 nc (netcat) 进行低级测试适用于 macOS/Linux在一个终端启动服务器并将其输出重定向到一个文件以便查看node server.js server_output.log 21在另一个终端使用nc连接到该进程通过管道# 创建一个命名管道 mkfifo /tmp/mcp_fifo # 将服务器的输入重定向到管道并从管道读取输出 tail -f /tmp/mcp_fifo | node server.js 21 | tee server.log # 现在可以向 /tmp/mcp_fifo 写入消息 echo {jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:Test,version:1.0}}} /tmp/mcp_fifo然后查看server.log文件中的响应。这种方法比较原始但能让你最直观地看到原始消息交换。更实用的方法与真实客户端集成最有效的测试是直接与你计划使用的客户端集成。例如在 Claude Desktop 中将你的server.js脚本打包确保#!/usr/bin/env node在文件首行并赋予可执行权限或通过package.json的bin字段配置。在 Claude Desktop 的 MCP 配置文件中添加你的服务器配置具体路径和格式请参考 Claude Desktop 文档。重启 Claude Desktop如果配置正确你应该能在聊天界面中看到get_current_time这个工具并可以调用它。4.4 进阶添加资源与动态更新让我们增强这个服务器添加一个“读取服务器日志”的资源并模拟动态更新工具列表。// ... 前面的 Server 实例化和 get_current_time 工具保持不变 ... // 新增声明一个资源模拟日志文件 server.setRequestHandler(resources/list, async () { return { resources: [ { uri: file:///internal/server_log.txt, name: 服务器内部日志, mimeType: text/plain, description: 本 MCP 服务器的模拟运行日志, }, ], }; }); // 新增处理资源读取请求 server.setRequestHandler(resources/read, async (request) { const { uri } request.params; if (uri file:///internal/server_log.txt) { return { contents: [ { uri: uri, mimeType: text/plain, // 资源内容也放在 text 字段中 text: [INFO] 服务器启动于 ${new Date().toISOString()}\n[INFO] 工具“get_current_time”已加载。, }, ], }; } throw new Error(资源未找到: ${uri}); }); // 新增模拟动态添加一个新工具例如5秒后 setTimeout(async () { // 首先更新服务器的工具列表逻辑 const newToolsList [ { name: get_current_time, description: 获取当前的系统日期和时间, inputSchema: { type: object, properties: {}, additionalProperties: false }, }, { name: echo, description: 回显输入的任何文本, inputSchema: { type: object, properties: { message: { type: string, description: 需要回显的文本 }, }, required: [message], additionalProperties: false, }, }, ]; // 这里需要替换之前的 handler或者用更动态的方式管理工具列表 // 为了简单演示我们直接替换 handler server.setRequestHandler(tools/list, async () ({ tools: newToolsList, })); // 关键主动发送一个 tools/list 通知给客户端告知列表已变更 // 注意SDK 可能提供了更优雅的推送方式这里演示协议层原理 // 实际中应使用 server.notify() 或类似方法如果SDK支持 console.log(JSON.stringify({ jsonrpc: 2.0, method: tools/list, params: { tools: newToolsList } }) \n); // 记得加换行符并刷新 if (process.stdout.flush) process.stdout.flush(); console.error(已动态添加“echo”工具并通知客户端。); }, 5000); // ... 后续的 server.connect 和 main 函数不变 ...这个进阶示例展示了资源声明与读取如何定义资源列表并在resources/read请求时返回内容。动态能力更新MCP 的核心优势之一。服务器可以在运行时更新其能力这里是工具列表并通过主动发送通知tools/list告知客户端。客户端收到后应刷新其工具列表。注意在实际 SDK 中通常有封装好的方法如server.notify()来发送通知上述直接console.log协议消息的方式比较底层仅用于演示原理。5. 协议调试、问题排查与最佳实践即使理解了协议在实际开发和集成中你一定会遇到各种问题。下面是我在多个 MCP 项目实践中总结的排查清单和经验。5.1 常见问题与排查指南问题现象可能原因排查步骤与解决方案客户端连接失败提示“无法启动服务器”1. 服务器脚本路径错误。2. 脚本没有执行权限。3. 运行环境依赖缺失如 Node.js 版本不对。1. 在终端手动运行服务器命令确认其能正常启动并阻塞。2. 检查客户端配置中的命令和参数是否正确。3. 确保脚本首行有正确的 shebang如#!/usr/bin/env node并已chmod x。连接成功但工具列表为空1. 服务器未正确处理initialize握手。2.tools/list处理器未设置或返回格式错误。3. 服务器在发送tools/list通知前崩溃。1.查看服务器日志确保initialize请求被收到且正确响应。2.检查消息流使用MCP Inspector或mcp-cli工具捕获通信流量确认tools/list通知是否发出且格式符合规范。3. 在tools/list处理器内部添加日志确认其被调用。调用工具时超时或无响应1. 服务器tools/call处理器有未捕获的异常。2. 工具执行耗时过长超过客户端超时设置。3. 响应消息格式错误客户端无法解析。1.检查服务器 stderr 日志通常未捕获的异常会打印到这里。2.在工具处理器中添加超时控制对于长任务考虑异步执行并立即返回一个“任务已接收”的响应再通过其他方式如下文通知传递结果。3.验证响应格式确保返回的result对象包含content: [{ type: text, text: ... }]结构。客户端收不到服务器的主动通知1. 客户端在initialize时未声明相应的capabilities如roots.listChanged: true。2. 服务器发送通知的格式或时机不对。3. 传输层问题如 STDIO 缓冲区未刷新。1. 确认客户端的initialize请求中包含了所需的能力声明。2. 使用调试工具捕获流量确认服务器是否发出了正确的通知消息method如tools/list且没有id字段。3.再次强调服务器在通过 stdout 发送任何消息后务必执行 flush 操作。消息解析错误1. 发送的 JSON 格式无效缺少引号、尾随逗号等。2. 未以换行符\n分隔消息。3. 消息中存在控制字符或编码问题。1. 使用JSON.stringify()生成消息避免手动拼接。2. 确保每条消息末尾都有\n。3. 对于复杂文本内容注意转义。在 Node.js 中可以借助JSON.stringify自动处理。5.2 调试神器MCP Inspector 与 mcp-cli工欲善其事必先利其器。手动模拟消息太低效了。推荐两个官方调试工具MCP Inspector一个图形化的调试工具可以连接到任何 MCP 服务器实时查看所有进出的消息并能手动构造请求发送。这对于理解协议交互流程、验证消息格式有无价的价值。安装npm install -g modelcontextprotocol/inspector使用mcp-inspector --command node --args /path/to/your/server.jsmcp-cli一个命令行客户端可以连接并交互式地测试 MCP 服务器。安装npm install -g modelcontextprotocol/cli使用mcp-cli --transport stdio node /path/to/your/server.js进入后可以输入list-tools,call-tool name等命令。在开发初期务必使用这些工具来验证你的服务器行为是否符合预期。5.3 开发与部署最佳实践输入验证与安全性工具的参数inputSchema一定要定义严格并利用 JSON Schema 的验证功能。在tools/call处理器中对传入的arguments进行二次验证防止注入攻击。特别是涉及文件操作、系统命令或数据库查询的工具。错误处理与友好提示在tools/call中使用try...catch包裹核心逻辑。发生错误时通过返回规范的error对象来告知客户端。error.message应尽可能对最终用户友好因为 AI 可能会直接读给用户听而详细的调试信息可以记录在服务器的日志中。资源消耗与超时管理AI 可能频繁调用工具。确保你的工具实现是高效且幂等的尽可能。对于耗时操作要设置明确的超时并考虑异步处理模式避免阻塞主线程导致整个 MCP 会话卡死。日志与可观测性将详细的日志输出到stderr包括收到的请求、处理步骤、遇到的错误等。这不仅是调试的需要也是线上运维的关键。可以考虑使用结构化的日志格式如 JSON。版本化与兼容性如果你的服务器会持续迭代考虑在initialize响应中提供版本信息。对于破坏性变更如工具签名改变最好通过提供新工具名如get_current_time_v2来保持向后兼容避免影响已集成的客户端。理解 MCP 协议的消息格式和传输层就像是拿到了 AI Agent 扩展能力的蓝图和施工手册。它不再是一个魔法黑盒而是一套你可以预测、调试甚至定制的清晰规范。从简单的 STDIO 服务器开始逐步尝试更复杂的资源和动态更新你会对如何构建一个强大、可靠的 AI 工具集成有更深的认识。在下一期我们将深入 MCP 的另一个核心概念资源Resources与上下文管理探讨如何高效地为 AI 提供海量、动态的外部知识。