1. 项目概述为什么我们需要关注 MCP 协议最近在折腾各种 AI 智能体开发时我遇到了一个几乎所有开发者都会头疼的问题如何让我的智能体轻松、稳定地连接和使用外部工具比如我想让一个基于 GPT-4 的智能体去读取我 Notion 里的待办事项然后根据内容自动在 GitHub 上创建 Issue最后再发个 Slack 通知。听起来是个很棒的自动化流程对吧但实现起来我得分别去研究 Notion API、GitHub API 和 Slack API 的认证、调用格式、错误处理……每个工具都是一座孤岛我得为每座岛单独造一艘船。这让我想起了早年的电子设备接口乱象。给手机充电你得认准是 Micro-USB 还是 Lightning传数据到电脑可能又得换根线。直到 USB-C 接口的出现它统一了物理形态和电力数据传输标准真正实现了“一线通”。现在AI 智能体生态也面临着类似的“接口”困境。而MCPModel Context Protocol协议在我看来就是 AI 时代的“USB-C”接口。它不是一个具体的工具或产品而是一套开放协议旨在为大型语言模型LLM与外部工具、数据源之间定义一个标准化的“对话”方式。简单说MCP 协议的核心价值在于“解耦”与“标准化”。它将智能体大脑和工具手脚分离开并规定了一套两者都必须遵守的通信规则。工具开发者只需按照 MCP 协议“说普通话”智能体开发者就无需关心这个工具内部是 Java 还是 Python 写的API 长什么样只需要知道它能“做什么”以及“怎么告诉它去做”。这极大地降低了智能体集成外部能力的门槛也让工具生态得以繁荣。你不再需要为每一个新工具重写一遍集成代码就像你不再需要为每一台新设备准备一根专属的数据线。2. MCP 协议核心设计思想与架构拆解要理解 MCP 为何能成为“标准接口”我们需要深入其设计哲学。它没有尝试去创造一个新的、更强大的模型也没有去替代现有的 API 标准如 RESTful、GraphQL而是在它们之上构建了一个抽象的、模型友好的交互层。2.1 核心组件Server, Client 与 Resources/ToolsMCP 协议的架构非常清晰主要包含三个角色MCP Server工具端这是外部能力或数据的提供者。一个 MCP Server 可以封装一个数据库、一个搜索引擎、一个文件系统甚至是一套复杂的业务逻辑。它的职责是向外界宣告“我这里有哪些资源Resources可以用有哪些工具Tools可以调用。” 例如一个“天气查询 Server”会宣告一个名为get_weather的工具并描述这个工具需要city和date两个参数。MCP Client客户端/智能体端这是能力的消费者通常是运行着 LLM 的应用程序或框架。例如 Cursor、Claude Desktop、或是你自己编写的智能体平台。Client 的核心职责是发现并连接一个或多个 Server获取它们提供的资源和工具列表并在需要时代表模型向 Server 发起调用请求。Resources资源与 Tools工具这是 Server 暴露给 Client 的具体内容。Resources可以理解为“只读”的数据源。比如一个 Server 可以提供file:///path/to/doc.md这样的文本资源或者https://api.example.com/data这样的动态数据资源。Client 可以读取它们的内容并将其作为上下文提供给模型。Tools则是“可执行”的操作。Client 可以调用 Tool并传入参数Server 执行后返回结果。这对应了模型“思考-行动-观察”循环中的“行动”环节。这种设计的关键在于Client 和 Server 之间的通信是声明式和标准化的。Server 不需要知道 Client 里跑的是 GPT-4 还是 Claude 3它只需要按照协议格式发送 JSON 消息Client 也不需要知道 Server 内部如何实现get_weather它只需要按照协议格式发起调用。协议本身就是它们共同的“语言”。2.2 协议通信流程一次标准的“握手”与“协作”让我们模拟一次典型的交互看看 MCP 如何在实际中工作初始化与握手Client如你的智能体开发环境启动并配置了需要连接的 MCP Server比如一个本地运行的“文件系统 Server”。Client 向 Server 发送初始化请求建立连接。能力发现Server 响应并发送一份清单列出它提供的所有Resources如file://./projects/README.md和Tools如read_file,write_file,list_directory。这份清单包含了每个资源的唯一标识、类型以及每个工具的名称、描述和参数模式通常用 JSON Schema 描述。上下文加载当用户向智能体提问“帮我总结一下./projects/README.md的内容。” Client 的 LLM 在思考过程中可能会决定需要先读取那个文件。于是Client 根据之前 Server 宣告的 Resource URI向 Server 发送一个read请求获取该文件的内容。工具执行LLM 在分析了文件内容后可能决定执行一个操作比如“将总结写入summary.txt”。这时LLM通过 Client会生成一个对write_file工具的调用请求包含path和content参数。Client 将这个结构化请求发送给 Server。结果返回Server 执行写文件操作然后将成功结果或错误信息返回给 Client。Client 将这个结果作为“观察”反馈给 LLMLLM 再基于此生成最终的回答给用户。整个过程中LLM 始终在与一个高度结构化的、可预测的接口交互而不是在“猜测”凌乱的 API 响应。这显著提高了复杂任务执行的可靠性和可控性。注意MCP 协议通常通过标准输入输出stdio或SSEServer-Sent Events进行通信。这意味着 Server 可以是一个独立的进程通过命令行启动与 Client 进程进行 IPC进程间通信。这种设计使得集成异常灵活任何能用脚本或程序封装的功能都可以成为一个 MCP Server。3. 实战从零构建一个自定义 MCP Server理解了原理最好的巩固方式就是动手实现一个。我们以构建一个“待办事项Todo管理 Server”为例它提供一个工具用于添加待办事项并提供一个资源用于列出所有事项。3.1 环境准备与 SDK 选择MCP 协议本身是语言无关的只要你能按照协议规范生成和解析 JSON 消息即可。但为了提升开发效率社区已经提供了多种语言的 SDK。这里我们选择使用TypeScript/JavaScript生态因为其工具链丰富且与当前很多 AI 开发环境如 Cursor集成良好。首先确保你已安装 Node.js版本 18。然后我们使用官方提供的modelcontextprotocol/sdk包。mkdir mcp-todo-server cd mcp-todo-server npm init -y npm install modelcontextprotocol/sdk3.2 定义 Server 能力Resources 与 Tools我们的 Todo Server 计划提供以下能力一个 Resourcetodo:///items当 Client 读取它时返回当前所有待办事项的列表。一个 Tooladd_todo_item接收task字符串参数用于添加新事项。我们先创建server.ts文件并定义 Server 的基本结构import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, Tool, } from modelcontextprotocol/sdk/types.js; // 初始化 Server const server new Server( { name: todo-list-server, version: 0.1.0, }, { capabilities: { resources: {}, // 声明我们支持 Resources 相关功能 tools: {}, // 声明我们支持 Tools 相关功能 }, } ); // 内存中存储待办事项 let todoItems: string[] [学习 MCP 协议, 编写示例 Server]; // 1. 处理 Client 查询可用 Tools 的请求 server.setRequestHandler(ListToolsRequestSchema, async () { const tools: Tool[] [ { name: add_todo_item, description: 向待办事项列表中添加一个新项目, inputSchema: { type: object, properties: { task: { type: string, description: 待办事项的具体内容, }, }, required: [task], }, }, ]; return { tools }; }); // 2. 处理 Client 查询可用 Resources 的请求 server.setRequestHandler(ListResourcesRequestSchema, async () { return { resources: [ { uri: todo:///items, mimeType: text/plain, // 我们以纯文本形式返回 name: 待办事项列表, description: 当前所有的待办事项, }, ], }; }); // 3. 处理 Client 读取 Resource 内容的请求 server.setRequestHandler(ReadResourceRequestSchema, async (request) { if (request.params.uri todo:///items) { // 将待办事项数组转换为易读的文本 const content todoItems.length 0 ? todoItems.map((item, index) ${index 1}. ${item}).join(\n) : 当前没有待办事项。; return { contents: [ { uri: request.params.uri, mimeType: text/plain, text: content, }, ], }; } // 如果请求的 URI 未找到抛出错误 throw new Error(Resource not found: ${request.params.uri}); }); // 4. 处理 Client 调用 Tool 的请求 server.setRequestHandler(CallToolRequestSchema, async (request) { if (request.params.name add_todo_item) { const { task } request.params.arguments as { task: string }; if (!task || task.trim() ) { throw new Error(任务内容不能为空); } todoItems.push(task.trim()); // 返回执行结果 return { content: [ { type: text, text: 已成功添加待办事项“${task}”。当前共有 ${todoItems.length} 项。, }, ], }; } throw new Error(Unknown tool: ${request.params.name}); }); // 启动 Server使用标准输入输出进行通信 async function main() { const transport new StdioServerTransport(); await server.connect(transport); console.error(MCP Todo Server 已启动并运行在 stdio 上...); } main().catch((error) { console.error(Server fatal error:, error); process.exit(1); });3.3 编译、运行与基础测试我们需要将 TypeScript 编译成 JavaScript 来运行。# 安装 TypeScript 编译器 npm install --save-dev typescript types/node # 初始化 tsconfig.json npx tsc --init --target ES2022 --module NodeNext --moduleResolution NodeNext --outDir ./dist # 编译 npx tsc编译后在dist目录下会生成server.js。我们可以用一个简单的脚本模拟 Client 来测试它。但更直接的方式是利用 MCP 协议基于 stdio 的特性我们可以手动通过管道发送 JSON 来测试。不过更高效的方法是使用一些现有的 MCP 测试工具或直接集成到支持 MCP 的 Client 中。一个快速的“冒烟测试”方法是直接运行 Server然后通过echo发送一个简单的 JSON 消息比如{jsonrpc: 2.0, id: 1, method: tools/list}到其标准输入观察输出。但这比较繁琐。对于日常开发建议将其配置到 Claude Desktop 或 Cursor 等直接支持 MCP 的应用程序中进行实测。3.4 集成到 Claude Desktop 进行实测以 Claude Desktop 为例其配置 MCP Server 的步骤非常直观找到 Claude Desktop 的配置文件。在 macOS 上通常位于~/Library/Application Support/Claude/claude_desktop_config.json。在 Windows 上位于%APPDATA%\Claude\claude_desktop_config.json。编辑该 JSON 文件在mcpServers字段下添加我们的 Server 配置。{ mcpServers: { todo-list: { command: node, args: [ /ABSOLUTE/PATH/TO/YOUR/mcp-todo-server/dist/server.js ] } } }重要提示args中的路径必须是绝对路径。保存配置文件后需要完全重启 Claude Desktop 应用不仅仅是关闭窗口可能需要从任务管理器或活动监视器中彻底退出进程。重启 Claude Desktop 后新建一个对话。如果配置成功当你输入“/”时应该能在工具列表中看到add_todo_item。你可以直接让 Claude“请使用 add_todo_item 工具帮我添加一个‘测试 MCP 集成’的待办。” Claude 会识别到这个工具并弹出参数框让你填写task内容。执行后你可以再问“列出我所有的待办事项。” Claude 可能会尝试去读取todo:///items这个资源并将列表呈现给你。通过这个简单的例子你可以清晰地看到我们编写的 Server 逻辑内存数组操作与 Claude 这个强大的 LLM 被 MCP 协议完美地连接了起来。Claude 不需要知道我们的 Server 是用 Node.js 写的它只关心协议约定的工具和资源。4. 高级主题生态、安全与最佳实践构建一个能跑的 Server 只是第一步。要让它在生产环境中可靠、安全地运行并为智能体生态创造价值还需要考虑更多。4.1 现有生态与热门 Server 解析MCP 协议之所以有成为“USB-C”的潜力离不开活跃的社区和丰富的现成 Server。了解它们能帮你避免重复造轮子并理解优秀的设计。文件系统类如filesystemServer允许模型安全地读写指定目录下的文件。这是最基础也最常用的 Server 之一。搜索引擎类如brave-search-mcp、tavily-mcp。它们将搜索能力封装成 Tool智能体可以调用search工具获取实时网络信息突破模型的知识截止日期限制。代码仓库类如githubServer可以克隆仓库、读取代码、创建 Issue 等是实现 AI 编程助手深度集成的关键。浏览器自动化类如playwright-mcp允许模型通过 Playwright 控制浏览器进行网页交互、数据抓取实现了智能体的“手和眼”。专用工具类如sqlServer执行数据库查询、curlServer发送 HTTP 请求等。实操心得在开发自己的 Server 前强烈建议先去 MCP 官方 GitHub 组织 或社区逛逛。很多场景可能已有成熟方案。使用这些 Server 时重点观察它们是如何设计 Tool 的命名、参数结构以及错误处理的这是宝贵的经验来源。4.2 安全考量与权限控制让 AI 模型直接操作你的文件系统、数据库或发送网络请求听起来威力巨大但也令人心惊胆战。MCP 协议设计时考虑了安全性但最终的安全边界需要由开发者来定义。最小权限原则这是最重要的准则。你的 Server 应该只暴露最必要的能力。例如一个文件系统 Server 应该被配置为只能访问某个特定的工作目录而不是整个硬盘。参数校验与净化Server 端必须对 Client 传来的所有参数进行严格的校验。例如在文件路径参数中要防止../../../etc/passwd这样的路径遍历攻击。在我们的 Todo Server 例子中虽然只是内存操作但也应对task参数做长度和内容的检查。身份认证与授权进阶对于需要访问敏感数据或执行高风险操作的 Server需要实现认证机制。MCP 协议支持在初始化阶段传递自定义的clientInfoServer 可以据此进行判断。更复杂的场景可能需要 OAuth 等流程但这通常需要在 Server 和 Client 应用层面做额外设计。沙箱化运行考虑将 MCP Server 进程运行在容器如 Docker或轻量级沙箱中以隔离潜在风险。警告切勿在未经严格审查和限制的情况下将拥有高危工具如shell、filesystemwith root access的 MCP Server 暴露给不受信任的模型或用户。这相当于给了 AI 一个系统级的 Shell 访问权限。4.3 性能优化与稳定性设计当你的 Server 开始处理真实负载时性能和稳定性就成为关键。连接管理一个 Client 可能连接多个 Server一个 Server 也可能被多个 Client 连接。要确保你的 Server 实现是无状态或能妥善管理会话状态的。对于资源密集型操作考虑连接池和超时机制。异步处理如果 Tool 的执行可能耗时较长如网络请求、复杂计算务必使用异步模式避免阻塞主线程导致整个 Server 无响应。JavaScript SDK 天然支持async/await要充分利用。错误处理与重试网络可能不稳定外部服务可能宕机。Server 应返回结构化的错误信息而 Client 端应实现适当的重试和降级逻辑。MCP 协议使用 JSON-RPC 2.0 的错误对象格式应遵循该规范。日志与监控为 Server 添加详细的日志记录包括收到的请求、处理耗时、错误信息等。这对于调试和后期性能分析至关重要。5. 常见问题与排查技巧实录在实际开发和集成 MCP Server 的过程中我踩过不少坑。这里总结一份“避坑指南”希望能帮你节省时间。5.1 连接与配置问题问题1Claude Desktop/Cursor 启动后看不到我配置的 MCP Server 工具。排查步骤检查配置文件路径和格式这是最常见的问题。确保 JSON 格式正确没有多余的逗号。特别是args中的路径必须使用绝对路径并且确保 Node.js 可执行文件node在系统 PATH 中或者使用完整路径如/usr/local/bin/node。检查 Server 启动日志在配置中可以尝试将stdio重定向到文件来查看 Server 的启动日志看是否有报错。例如在配置中增加env: {NODE_DEBUG: transport}等环境变量来开启 SDK 的调试日志。彻底重启 Client 应用很多时候仅仅关闭窗口是不够的需要在任务管理器Windows或活动监视器macOS中彻底结束进程再重新启动。检查端口或 IPC 冲突如果你使用的是 SSE 传输方式确保指定的端口没有被占用。问题2调用工具时返回“Tool not found”或“Internal JSON-RPC error”。排查步骤核对工具名确保 Client 调用的工具名称与 Server 在ListToolsRequest响应中声明的name字段完全一致包括大小写。检查 Server 日志查看 Server 端是否有未捕获的异常。一个未处理的错误可能导致整个请求链崩溃返回模糊的内部错误。验证参数结构确保 Client 发送的参数对象完全符合 Server 定义的inputSchema。多一个字段、少一个字段或者字段类型不匹配都可能导致调用失败。5.2 开发与调试技巧技巧1使用mcp-cli或mcp-client进行快速测试。在开发 Server 时不必每次都集成到 Claude Desktop 这样的大型应用中进行测试。可以使用社区提供的命令行客户端工具它们能模拟标准 Client 的行为方便你快速验证 Server 的基础功能。# 假设你有一个用Rust编写的MCP Server npx modelcontextprotocol/mcp-cli ./your-server-binary # 连接后你可以手动发送 list_tools, call_tool 等指令进行测试。技巧2在 Server 代码中开启详细调试日志。在开发初期在 Server 的每个请求处理函数开始和结束处打印日志能帮你清晰看到数据流动。server.setRequestHandler(CallToolRequestSchema, async (request) { console.error([DEBUG] 收到工具调用请求: ${JSON.stringify(request)}); // ... 处理逻辑 console.error([DEBUG] 工具调用返回结果。); return result; });技巧3注意资源 URI 的设计。URI 是资源的唯一标识。设计时应遵循清晰、有层次的原则。例如对于一个数据库 Server可以使用db:///main/users/123这样的格式来表示“main 数据库下 users 表中 id 为 123 的记录”。避免使用过于随意或可能冲突的 URI 命名。5.3 设计模式与架构思考思考1何时用 Resource何时用 Tool这是一个常见的困惑。我的经验法则是Resource用于表示状态或数据通常是只读的或者其“写”操作通过独立的 Tool 完成。例如一个配置文件、一张数据库表视图、一个传感器的当前读数。它的内容可以被 Client 拉取并注入到模型的上下文中。Tool用于表示一个动作或命令它会改变某些状态并返回一个结果。例如“发送邮件”、“创建订单”、“重启服务”。它的调用是模型“行动”的体现。有时两者可以结合。例如一个gitServer 可以提供git:///repo/status这个 Resource 来展示仓库状态同时提供git_commit这个 Tool 来执行提交操作。思考2如何处理复杂、多步骤的交互有些操作不是一次 Tool 调用就能完成的。例如一个“订机票”流程可能需要先search_flights然后select_seat最后make_payment。MCP 协议本身不直接管理会话状态这需要开发者自己设计。方案一Server 维护状态在 Server 端维护一个简单的会话状态例如用一个 Map 存储会话 ID 和临时数据。在第一个 Tool 调用时生成一个sessionId并返回后续调用必须带上此sessionId。这要求 Client或模型有能力记住并传递这个 ID。方案二Client 维护状态将多步骤流程拆解成完全独立的 Tool但要求模型在上下文中记住前序步骤的关键结果如航班号并将其作为参数传递给下一步。这更符合 LLM 的工作方式但对模型的逻辑能力要求更高。目前更推荐方案二因为它更简单、无状态且将流程控制的复杂性交给了更擅长此道的 LLM。Server 只负责原子操作。MCP 协议的出现正将 AI 智能体开发从“手工作坊”阶段推向“标准化工业”阶段。它解决了工具集成的“最后一公里”问题让开发者能更专注于智能体本身的逻辑与体验。就像 USB-C 统一了接口混乱的局面MCP 有望成为连接 AI 大脑与万千数字世界的标准总线。现在正是深入理解并参与构建这一生态的好时机。从我自己的体验来看一旦你习惯了这种“声明式”的集成方式就很难再回头去写那些脆硬的、一对一对接的 API 胶水代码了。