MCP协议入门：从Agent工具调用到自建MCP Server的完整实践

如果你也遇到过这样的场景——想让 Agent 根据 Figma 设计稿自动生成一套前端代码结果它连设计稿的图层都读不到想让 Agent 帮你把一份 PDF 转成结构化 JSON结果它只会给你口述转换步骤——那你大概能理解AI Agent 的瓶颈从来不在“能不能想出方案”而在“能不能碰到真实世界的工具”。MCPModel Context Protocol模型上下文协议就是为了解决这个卡点而出现的开放协议。它有点像给模型配了一个万能电源插座任何支持 MCP 的客户端插上就能调用任意 MCP Server 提供的真实工具无论是读文件、操作浏览器、访问数据库还是调用设计稿、运行安全扫描器。这篇文章我不打算只讲概念而是从为什么需要它、底层机制是什么、现在有哪些能用的 Server到自己动手写一个 Server、接入真实客户端、调试排错的完整链路一次性讲透。它适合谁看正在做 Agent 开发、AI 应用集成、工具链建设的人或者只是被“Agent 总是编造结果”折磨过的朋友。读完你应该能明白MCP 到底改了什么以及为什么 2024 年底至今它会成为 Agent 生态里最热的基础设施之一。1. 从“会聊天”到“能办事”Agent 卡住的那一步叫什么1.1 有大脑没手脚Agent 的真实困境聊 MCP 之前得先把 Agent 的本质说清楚。一个 AI Agent 之所以叫 Agent而不是聊天机器人是因为它有“感知—决策—行动”的闭环模型负责拆解任务、出方案但最终执行必须落到真实世界的某个动作上。举个例子。我接过一个很典型的需求让 Agent 定时读一个销售周报 Excel提取关键数字写进数据库再生成一张趋势图邮件发出去。这个流程里模型背后要干四件事打开文件、解析单元格、连接数据库、调绘图接口。问题是大模型本身只是个“文本进文本出”的系统它并不具备直接操作 Excel 和数据库的能力。没有工具调用机制它就只能告诉你“你应该这样写代码”然后啥也干不成。那时候业界的常见做法是 function calling模型厂商在 API 里定义好一系列函数的 JSON Schema模型在回答时能生成一个“我要调用这个函数参数是什么”的请求然后由开发者自己的代码去执行。这套思路本身没问题但真正落地时很疼。1.2 传统集成方式为什么疼每一次接入都是 N×M我做过一段时间的 Agent 项目集成最深的感觉是function calling 把“让模型决定调用工具”这件事标准化了但“工具怎么被外界发现、怎么配置、怎么连接”完全没有统一标准。你需要在自己代码里为每一个工具写一遍注册逻辑每隔一段时间就有一个新的模型版本发布厂商对 function calling 的约束和写法时不时还变一下。更麻烦的是你辛辛苦苦接好了一个 PDF 解析服务换一个客户端比如从某 API 换到另一个桌面应用就全部重来。我当时给三个不同的 Agent 客户端接同一套内部工具写出来的代码几乎没有一行能复用。这就是经典的 N×M 问题N 个模型 × M 个工具每对接一个组合就要重复造一次轮子。而当你想把 Figma、浏览器、数据库、安全扫描器这些“重型工具”统一交给 Agent 时麻烦会指数级放大。1.3 MCP 的解法把工具变成协议MCP 的思路很直接既然模型和工具之间总要有个“中间人”那不如把“中间人”的交互方式做成标准协议让任何 AI 客户端都能去发现和调用任何工具服务端。这个关系有点像 USB-C以前你每买一台设备就要配一条专用的线现在只要接口统一一根线走天下。MCP 由 Anthropic 在 2024 年 11 月开源随后整个生态以极快的速度膨胀。OpenAI 在 2025 年明确宣布支持 MCP微软、Google 也陆续加入了阵营这也让 MCP 从一个“Claude 专用协议”变成了事实上的开放标准。现在的格局是模型侧你随便换工具侧你随便换中间通过 MCP 连接。原来 N×M 的接入成本被压缩成了 NM。这也是为什么 2025 年之后“MCP Server”这个词频繁出现在各种 Agent、AI 应用的热搜列表里。2. MCP 的底层逻辑三层架构、三大原语与一条 JSON-RPC 通道2.1 Host、Client、Server 三层角色MCP 的架构看起来复杂实际上只有三层角色Host宿主、Client客户端、Server服务端。角色职责典型例子Host用户交互界面负责承载整个会话决定“何时调用工具”Claude Desktop、Codex CLI、自研的 Agent 应用Client在 Host 内部维护与某个 Server 的连接负责协议握手、请求转发由 SDK 生成你通常不会直接感知Server向外界暴露工具、资源、提示词执行真实操作文件读取工具、Figma MCP、Playwright MCP我最初看到这套分层的时候有点困惑Host 和 Client 不都是客户端吗为啥要拆开后来才明白一个 Host 可以同时连接几十个 Server每个 Server 对应一个独立 Client 连接。你把 Client 当成“每根连接线的插头”Host 是插座面板Server 是墙后面的电器这个比喻就很清楚了。在实际开发里你写的 MCP Server 只需要关注“如何把自己能提供的工具描述清楚、如何执行工具调用”剩下的握手、鉴权、消息封装都由 MCP SDK 处理好。这也意味着一个 Server 写好之后理论上 Claude、Cursor、Codex、自研应用都可以直接用。2.2 Tool、Resource、Prompt 三个原语分别解决什么MCP 定义了三个核心原语刚接触时容易混淆我逐个说一下。Tool 是“可执行的动作”类似于函数调用。每个 Tool 必须有 name唯一标识、description告诉模型什么时候该用它、schema参数结构。模型通过 tools/call 请求调用某个 ToolServer 执行后返回结果。这是 MCP 里使用最频繁的原语。你可以把它理解为给 Agent 装了一排按钮每个按钮代表一个真实能力模型自己决定按哪个。Resource 是“可读取的数据”用 URI 定位。它解决的是“模型需要上下文但不需要执行动作”的场景比如读取某个文件内容、读取某个 URL 的页面。和 Tool 的区别在于Resource 不改变外部状态只是把数据喂给模型。Prompt 是“可复用的提示词模板”。这个原语在界面上最容易被忽略实际上它能解决大量重复工作。你可以预置一个“代码审查专家”的 Prompt 模板通过 prompts/get 获取后自动填入当前任务。三个原语合起来其实覆盖了 Agent 工作的三种基本模式读数据、做动作、套流程。2.3 JSON-RPC 与两条传输通道stdio 和 HTTPMCP 的消息层基于 JSON-RPC 2.0一种非常轻量的远程调用协议。一次典型的 MCP 交互会有这么几步客户端向服务端发送 initialize 握手请求确认协议版本和能力。客户端调用 tools/list获取服务端支持的所有工具清单。模型根据任务决定调用哪个工具客户端发送 tools/call 请求。服务端执行操作返回结构化结果。这个流程很像你打开一个点餐小程序先确认店铺营业再拉菜单选菜下单最后等后厨出餐。每一步都有标准消息格式所以不同实现之间可以互相通信。传输层目前最常见的有两种stdio 和 Streamable HTTP。stdio 模式是服务端通过标准输入输出与客户端交换消息默认适合本地场景安全、简单、不需要开端口。远程服务则推荐 Streamable HTTP通过 HTTP POST 请求交互还支持服务端推送。写本地工具时用 stdio 就够了。3. 设计稿、浏览器、安全测试、3D 建模热门 MCP Server 逐个拆解3.1 设计交付里的“切图自由”蓝湖 MCP 与 Figma MCP设计类 MCP 是这轮生态里讨论度最高的分支原因很简单设计稿是前端开发的高频物料以往人肉切图、对标注实在太痛苦了。先说 Figma MCP。很多人搜索一个问题Figma MCP 可以直接切图吗我的回答是能但不是你想象的那种“一键导出全套切图”。Figma MCP 能读取画布结构、图层树、选中节点的样式属性也能把某个节点导出为图片或 SVG。你可以让 Agent“读取 Frame 123:456 里的所有文本节点和颜色属性”它能把设计信息变成结构化数据交给你。但要注意它导出的是原始素材距离真正能上线的切图还差工程化的一步命名规范、dpr 尺寸、压缩格式这些仍然需要你在代码里做处理。相比之下蓝湖 MCP 更像一个“交付平台摄像头”接上之后 Agent 能读取蓝湖上的设计标注、切图资源、交互原型说明对做设计和开发的协作场景非常友好。我实际用下来的体会是设计类 MCP 最适合的场景不是“全自动切图”而是“把设计稿当作上下文给 Agent”。让 Agent 看着某个按钮的样式描述去写对应代码比传一张截图让它自己猜要准确得多。当然接入这类 Server 时必须注意账号授权范围别把企业私有设计稿的读取权限开给所有会话。3.2 浏览器自动化Playwright MCP浏览器操作是另一个高频场景微软的 Playwright MCP 几乎是这个领域的标配。通过它Agent 可以直接控制一个真实浏览器打开页面、点击按钮、填写表单、截图、抓取网页内容、读取控制台日志甚至跑性能分析。我做过一个简单的实验用 AI 客户端连上 Playwright MCP让它“打开我指定的页面把页面上所有外链收集起来逐个访问并判断是否有返回 404”。整个过程 Agent 自己拆解成“先抓链接再逐个访问最后汇总”这样的多步计划然后通过 MCP 工具一步步执行中间还会根据页面实际加载情况调整策略。这里有个经验浏览器自动化虽然强大但网站的验证码、登录态、反爬机制都会让 Agent 卡壳。建议在 Prompt 里明确告诉 Agent“遇到弹窗和验证码不要硬闯直接记录异常”同时给 Playwright 操作设置合理的超时时间。另外把浏览器自动化用于抓取数据前一定要确认目标网站的规则和合规要求。3.3 安全测试与逆向分析Burpsuite MCP、Yakit MCP、IDA MCP安全圈子也迅速拥抱了 MCP。Burpsuite MCP 让 Agent 能调用 Burp Suite 的代理、扫描器、重放器能力在授权渗透测试中你可以让 Agent 配合流量日志分析漏洞、重新发送构造的请求。Yakit MCP 则把国产安全测试平台的能力开放出来支持调用各种插件化能力。IDA MCP 面向逆向工程让 Agent 可以查询函数列表、反汇编代码、交叉引用对漏洞研究和 CTF 解题帮助很大。这里必须反复强调一点所有这些能力都只能在“你有明确授权的系统”上使用。安全测试的前提是合规MCP 只是把工具接入打通做不做、对谁做责任完全在你自己。我在团队内部推 MCP 时第一条规定就是涉及扫描、重放、渗透类 Server一律先配置网络白名单和审计日志绝对不允许连到未授权目标。从效率角度说安全类 MCP 最实用的地方是“辅助分析”让 Agent 读一段流量记录、帮你梳理攻击面或者解释某段反汇编的逻辑。原来你要在多个工具间切换、复制结果现在模型可以直接调工具拿数据整个分析链路顺了很多。3.4 从 Blender 到一切3D 建模与行业扩展想象除了上面这些MCP 的生态已经蔓延到很多你未必想得到的工具。Blender MCP 是一个让我印象深刻的例子它把 Blender 的建模、材质、渲染能力暴露给 Agent你可以直接说“生成一个低多边形小木屋屋顶是红色的”Agent 会通过 MCP 调用 Blender Python API 真的一步一步把模型建出来。这个案例的好玩之处在于它证明 MCP 不局限于“数据流”型工具还能对接“创作流”型工具。数据库连接器、邮件客户端、日历、知识库、微信机器人、监控系统凡是有标准 API 或命令行工具的东西理论上都能包一层 MCP Server 交给 Agent 使用。当你的 Agent 同时挂着一个文件 Server、一个浏览器 Server、一个数据库 Server 时它才真正像一个能独立干活的数字员工。4. 自己动手写一个 MCP Server代码、调试与客户端接入4.1 先选工具官方 SDK 还是 FastMCP如果你想涉足 MCP 开发第一个选择题是用官方 SDK 还是第三方的 FastMCP。官方提供 Python 和 TypeScript 两种 SDK功能最完整适合对协议细节有掌控欲的人但你需要自己处理一些样板代码。FastMCP 是在官方 SDK 之上封装的 Python 框架用装饰器就能快速定义工具代码量少很多特别适合做原型验证、内部小工具。我的建议是练手和内部工具用 FastMCP生产环境、需要深度定制鉴权和传输方式时再回到官方 SDK。理由很简单FastMCP 让你在 20 分钟内体验到“写完一个工具马上被 Agent 调用”的正反馈这个对理解 MCP 模型太重要了。4.2 从零写一个“文件工具箱”Server下面我用 FastMCP 写一个极简但完整的文件工具箱提供两个工具列出目录内容、读取文件内容。# file_tools_server.py import os from fastmcp import FastMCP mcp FastMCP(FileTools) mcp.tool() def list_files(path: str) - str: 列出指定目录下的所有文件和子目录。 try: entries os.listdir(path) return \n.join(sorted(entries)) except Exception as e: return f目录读取失败: {e} mcp.tool() def read_file(path: str, max_chars: int 2000) - str: 读取文本文件内容最多返回 max_chars 个字符。 try: with open(path, r, encodingutf-8, errorsignore) as f: return f.read(max_chars) except Exception as e: return f文件读取失败: {e} if __name__ __main__: mcp.run()注意几个细节装饰器里的函数名就是工具名docstring 会变成工具描述参数和返回类型会被自动转换成 JSON Schema。运行python file_tools_server.py后程序默认以 stdio 模式启动等待客户端连接。你看到屏幕“没反应”是正常的它不是卡死而是在等 JSON-RPC 消息从标准输入流进来。这个例子虽然简单但已经覆盖了 MCP Server 开发的完整链路定义工具、暴露描述、执行调用、返回结果。等你把这个跑通再去读官方文档很多概念都能对上号。4.3 本地调试三板斧日志、Inspector、手动调用写 MCP Server 最难受的环节是调试因为你自己没法直接在终端里呼它。我总结了三板斧。第一板斧所有调试输出走 stderr千万别用 print 打到 stdout。stdio 模式下stdout 是协议通道你一个 print 输出普通文字客户端和 Server 双方都无法解析消息立刻报协议错误。FastMCP 的日志默认走 stderr如果你自己写插件或自定义工具也要遵守这个规则。第二板斧使用 MCP Inspector 可视化调试。它是官方提供的调试工具启动方式很简单npx modelcontextprotocol/inspector python file_tools_server.py启动后浏览器会打开一个调试面板能看到 tools/list 返回的完整工具清单可以手动填参数调用某个工具查看返回结果。这比猜“为什么 Agent 不调用我的工具”高效得多。第三板斧先手动验证核心逻辑再谈 Agent 调用。我在写工具时习惯先单独写个测试脚本调用函数本身确认业务逻辑没问题后再包成 MCP Tool这样可以避免把“业务 bug”和“协议 bug”混在一起排查。4.4 接入真实客户端Claude Desktop 与 Codex CLI写好了 Server接下来就是让真实客户端连上来。Claude Desktop 的配置文件是claude_desktop_config.json在配置的 mcpServers 里注册一个条目即可{ mcpServers: { file-tools: { command: python, args: [/Users/your_name/projects/file_tools_server.py] } } }注意两点command 建议写完整路径args 里的脚本路径也尽量用绝对路径避免因环境变量不同导致启动失败。Windows 上如果遇到窗口闪退可以尝试用pythonw代替python或者在命令行先手动跑一遍脚本看报错。Codex CLI 也支持通过配置文件注册 MCP Server核心逻辑和上面一致只是配置文件路径和字段名略有差异以官方文档为准。接入之后你在对话里直接问“帮我列出某个目录的文件”模型就会决定调用 list_files 工具并把返回结果组织成自然语言回复。整个过程跑通之后你对 MCP 的理解会有一个质的飞跃它只是一个非常薄的标准层真正干活的还是你的工具代码。5. 接入真实世界的另一面权限边界、失败排查与不乱用 MCP5.1 权限边界设错了Agent 会怎么翻车MCP 给 Agent 打开了一扇通往真实世界的门但同时也意味着如果这扇门的权限设置不当Agent 就能以你的身份干很多事。我认真提醒一句Agent 没有常识只有概率。它不知道“删除线上数据”和“删除一个临时文件”之间的轻重区别如果你给它暴露了 Shell 工具、数据库写权限、云平台删除权限一次幻觉就可能酿成事故。我见过一个案例同事给 Agent 接了一个数据库 MCP Server本来只想让它查询订单数据顺手把更新权限也暴露了。结果 Agent 在执行任务时因为理解偏差执行了一条 UPDATE把一批订单状态改错了。事后排查不是工具写错了而是“工具能力范围”定义得太宽。因此在设计 MCP Server 时我把“最小权限原则”当成第一优先级能只读就不给写能限定路径就限定路径能限定表就不给整个库。高危操作比如删除、批量更新、汇款一定要在工具层做好二次确认或者在 Server 里强制记录审计日志。你可以让 Agent 越聪明但不能让它越权限。5.2 Agent 调用工具失败时从这几个环节按顺序排查Agent 调用工具失败是最容易让人抓狂的情况。每次遇到我都会按下面这张表去排查效率很高排查环节典型症状检查方式Server 是否正常运行工具列表为空、客户端提示“Connection failed”命令行直接运行 Server确认进程能起来客户端是否加载到工具模型说“我没有这个工具”看调试面板或 tools/list 返回结果参数是否匹配 Schema报错 missing required argument查看 Server 日志中的参数校验信息权限与工作目录文件读不到、命令执行失败确认 Server 进程的工作目录、用户权限模型是否真的打算调用模型绕开工具直接回答检查提示词是否明确要求使用工具其中最后一条最隐蔽。有时并不是工具坏了而是模型的提示词里没有强调“必须调用工具”它就直接根据训练知识编了一个答案。我踩过好几次这个坑现在写 Prompt 会明确加上“遇到这类问题必须调用相应 MCP 工具禁止直接猜测”。5.3 不是所有场景都需要 MCP和 function calling 怎么选聊到最后我必须泼一点冷水MCP 很火但不代表所有工具接入都必须用它。如果你只是在某一个模型 API 内部调用十几个私有函数function calling 已经足够因为它更轻、无需额外维护 Server 进程。如果你的工具只服务某一个特定平台那该平台的插件体系往往更顺手。MCP 最大的价值在于“跨应用、跨模型复用”。你需要把它看作一个长期资产一个设计良好的 MCP Server今天给 Claude 用明天给 Codex 用后天给你自己写的 Agent 框架用都能无缝接入。所以我的经验是先从一个高频、低风险的场景开始引入 MCP比如“文档阅读”“网页信息采集”这种只读类工具跑顺了再逐步放开到写操作。这个节奏既能让团队建立对 Agent 的信任也能避免一开始就把权限敞得太大。最后分享一点我自己的切身体会MCP 协议本身一点都不复杂真正考验人的是你如何设计工具的“边界”和“语义”。一个工具描述是否清晰决定模型会不会在合适的时机调用它一个工具的权限范围是否克制决定 Agent 接入真实世界后是帮手还是风险源。先把这两件事想清楚再动手写代码你一定能比大多数人少踩很多坑。