如果你最近在刷AI相关的技术社区十有八九会撞见MCP这三个字母。Model Context Protocol模型上下文协议被不少人喊成AI界的USB-C接口。一个底层协议能被传得这么热闹确实有它的道理。它解决的是所有AI Agent开发者的共同痛点模型怎么按需接外部工具、怎么访问私有数据、怎么让不同系统之间不用给每种工具单独写一套硬编码适配层。这篇文章我从实际开发者的角度把MCP的定位、协议里的核心设计、怎么从零写一个能跑的MCP Server、以及Figma、Playwright、蓝湖这几个真实场景逐个拆开讲一遍。打算做Agent集成、或者单纯想搞懂这个AI圈热词到底在说什么的开发者都能在里头找到直接能用的东西。1. 没有MCP之前Agent接工具为何乱成一锅粥1.1 工具链的手工作坊时代先回忆一下没有MCP的时候一个AI Agent要调用外部工具是个什么画风。假设你想让模型帮你查数据库。最简单的做法是写一个函数让模型生成SQL然后你执行这段SQL把结果丢回给模型。听起来很顺但实际落地远没那么简单模型并不知道你的数据库长什么样有哪些表、哪些字段、字段的类型和含义是什么你得先通过系统提示词把表结构塞给它。更麻烦的是如果Agent要接的不是数据库而是Slack、飞书、GitHub、浏览器、设计稿那就要为每一个服务单独写一套API封装。我当时写过一个小项目Agent要同时调用日历API和邮件API。两边认证方式不一样、返回字段命名不一样、错误码也不一样于是我在服务端写了两个模块分别对接再在Prompt里分别写清楚日历工具的参数是什么、邮件工具的参数是什么。一旦上游接口改个字段名我的代码和Prompt描述都要同步改。这还只是两个工具如果接十个、二十个光是维护这套私有接口说明文档就足够让人崩溃。这就是整个AI工具集成的现状每个工具都是独立插座Agent的插头得适配每个插座。模型层面上工具调用没有统一描述标准工程层面上没有任何通用的协议来接管工具发现、调用、结果返回这一整套链路。1.2 MCP想让事情变简单MCP想做的事说白了就是给这些工具外面套一层标准外壳。工具方只需要实现一次MCP服务端任何支持MCP的客户端——无论是Claude桌面版、各类IDE插件还是你自己写的Agent——都能自动识别这个工具长什么样、该按什么参数调用、调用完结果按什么格式返回。这跟某某的USB接口是一个道理。以前你出门要带好几条线因为不同设备接口不一样后来大家约定用同一个口线材就通用了。MCP想当的就是这条通用线工具能力提供方只要实现好这一个口AI客户端就不用再针对每个工具写私有的对接逻辑。另一个容易被忽略的好处是MCP把工具描述和调用入口合并成了一个动态资源。过去把工具信息写死在Prompt里模型规模一大、上下文一长效果好不起来。MCP Server可以主动暴露自己的工具列表、参数格式、提示词模板客户端按需获取这样模型的上下文压力会小很多。这也是它被越来越多人接受的原因——不是又发明一个格式而是把工具如何被发现、如何被调用、结果如何返回整个标准化了。2. MCP协议的核心设计拆解2.1 三个核心角色Host、Client、ServerMCP的架构其实非常传统一个服务端一个客户端中间一个协调者。角色说明你熟悉的例子Host宿主用户交互的入口管理多个ClientClaude Desktop、Cursor、IDE插件Client客户端与某个Server建立连接负责协议通信每个MCP Server对应一个Client实例Server服务端暴露工具、资源、提示词能力的独立进程或服务自建的数据库工具、Figma MCP Server等一个Host可以同时连接多个Server。比如你在Claude Desktop里同时配了文件系统MCP、数据库MCP和Figma MCPHost会为每一个Server创建一个独立ClientClient之间互不干扰。这种Host—多Client—多Server的设计是MCP实用主义的体现它不想做一个中心化的万能工具层而是让不同的工具跑在不同的进程甚至不同的机器上一个挂了不影响其他。从开发者的视角看你大多数时候只需要担心两个东西第一我的Server暴露了什么能力第二它用的是哪种传输通道。剩下的事情协议本身都替你定义好了。2.2 三种核心原语Tools、Resources、PromptsMCP把Server对外能提供的东西抽象成三类Tools、Resources、Prompts。Tools是最接近函数调用的东西。一个工具就是一个可执行的操作比如查天气执行SQL发送消息。它必须有名字、描述、JSON Schema参数定义。模型根据这些描述决定要不要调用、传什么参数。这一块对应的是《Function Calling》的标准场景只是MCP把函数定义和函数体拆在了Server一侧客户端不用在代码里写死函数签名。Resources可以理解成可读取的内容资源。它不执行操作而是暴露数据。比如一个文件路径、一个数据库表格结构、一个项目文档。和Tools强调动作不同Resources强调的是内容。客户端可以通过URI去读它就像用HTTP GET拉一个网页一样。Prompts是一套可复用的提示词模板。Server可以预置总结当前代码仓库生成数据库表结构文档这样的提示词模板客户端和用户可以像调用快捷指令一样把它们插入当前对话。这个设计非常适合团队协作场景团队把常用工作流固化成Prompts大家使用时体验一致不用每个人手敲一遍Prompt。实际开发中这三类能力可以混用。比如我自建了一个代码仓库MCPResources用来暴露项目文件内容Tools用来执行git操作和读issue列表Prompts里放按提交记录写周报的模板。整个Agent的开发体验比过去把所有信息堆在System Prompt里清晰太多。2.3 传输层stdio 与 Streamable HTTPMCP当前的主流传输方式有两种标准输入输出stdio和基于HTTP的流式传输。stdio模式下MCP Server作为一个子进程启动与客户端通过标准输入输出通信。这种模式最省事不需要开端口、不需要处理跨域适合本地跑的工具。Claude Desktop和大部分本地MCP配置默认用的就是它。代价是Server和Client必须同机部署而且进程生命周期得跟着客户端走。Streamable HTTP则是服务端模式。你用Flask、FastAPI之类的框架把MCP能力暴露成一个HTTP端点远程客户端通过URL访问。这样多个客户端可以共享同一个Server适合部署在服务器上的共享工具。我在本地调试阶段一般都用stdio毕竟日志、报错都在同一个终端里排查问题直观。等到Server稳定了再根据实际需要包装成HTTP服务。这个路径几乎适合所有MCP项目。3. 动手写一个完整的MCP Server3.1 环境准备我先说结论写MCP Server并不需要什么高深的知识你只要会Python或者TypeScript然后装一个官方SDK就能起步。Python那边用mcp官方库建议用fastmcp这个封装层代码体感非常接近FastAPI团队里新人也容易上手。Node.js生态用modelcontextprotocol/sdk。我个人更喜欢Python版本因为后续如果要接pandas、numpy做数据处理直接在MCP Server内部搞定不用再单独起一个微服务。准备阶段就是创建虚拟环境、安装依赖mkdir demo-mcp-server cd demo-mcp-server python3 -m venv .venv source .venv/bin/activate pip install mcp[cli]装完可以用mcp --help验证一下CLI是否可用。这个CLI自带了一个开发者调试工具后面排查问题会非常有用。3.2 Server代码解析下面这个例子我写的是一个待办事项工具Server暴露了两个Tools——新增待办、查询待办数据放在内存里。麻雀虽小但能完整展示MCP Server的结构。from mcp.server.fastmcp import FastMCP mcp FastMCP(todo-server) # 用一个列表模拟数据库 todos [] mcp.tool() def add_todo(title: str, priority: str medium) - str: 添加一条待办事项。 item {title: title, priority: priority, done: False} todos.append(item) return f已添加{title}优先级{priority} mcp.tool() def list_todos(only_undone: bool False) - list[dict]: 列出待办事项可只查看未完成项。 if only_undone: return [t for t in todos if not t[done]] return todos if __name__ __main__: mcp.run()这段代码里最关键的是mcp.tool()装饰器。SDK会根据函数签名和类型注解自动生成JSON Schema描述客户端拿到的工具定义大致长这样{ name: add_todo, description: 添加一条待办事项。, inputSchema: { type: object, properties: { title: { type: string, description: 待办标题 }, priority: { type: string, enum: [low, medium, high] } }, required: [title] } }这里有一个容易被忽略的细节函数的docstring和参数类型注解不是摆设它们会被直接转化成给模型看的工具描述。如果docstring写得含糊模型就不知道这个工具在什么场景该不该调用。我曾经在一个项目里把某个工具的描述写成This function does something related to data结果模型在该调用它的时候频繁出错改成具体描述后准确率肉眼可见地提升。把工具当API文档一样写是MCP开发的基本功。3.3 在客户端里配置和验证Server写好后第一步不是直接扔进Claude而是用MCP官方CLI自带的调试工具快速验证。mcp run todo-server.py这样会启动一个交互式终端你可以手动输入JSON-RPC报文来调用tools/list和tools/call确认工具定义和返回值都正常。验证通过后再把Server挂到支持MCP的客户端。以Claude Desktop为例配置文件一般在claude_desktop_config.json{ mcpServers: { todo-server: { command: /path/to/.venv/bin/python, args: [/path/to/todo-server.py] } } }很多新手在这里栽的第一个跟头是command直接写python结果子进程起不来。原因是Claude Desktop启动Server时用的是系统默认PATH未必和你终端里的虚拟环境PATH一致。所以我在配置里永远写虚拟环境里的绝对路径Python解释器不然很容易出现终端里能跑客户端里找不到模块的诡异问题。配置完成后重启客户端新建对话里大概率会出现工具提示。你可以直接发一句帮我添加一条优先级为高的待办周五前写完方案然后观察Agent是否正确触发了add_todo工具。这一步通了你的第一个MCP Server就算跑起来了。4. 值得关注的MCP生态场景4.1 Figma和蓝湖设计稿转代码的效率革命设计稿转代码是MCP目前最火的应用方向之一代表就是Figma MCP和国内蓝湖的MCP服务。传统流程里开发者拿到设计稿后要自己看标注、切图、量间距再手动写CSS。现在通过MCPAI编程工具可以直接读取Figma文件里的图层、样式、颜色、间距信息然后结合项目代码库的上下文生成接近还原度的前端代码。我实际测试过几次。前提是设计稿的图层命名规范组件层级清晰。在这个前提下AI生成的页面在布局和配色上能到七八成的还原度。特别是在Tailwind CSS、CSS Modules这类约定式样式的项目里AI基于设计稿的标注信息生成代码比单纯看截图去猜要靠谱得多。这也是为什么很多人问Figma MCP能不能直接切图——答案是能但前提是你在Figma侧把切图标记做好MCP读取到的是设计数据不是像素图。蓝湖作为设计协作平台这波跟进得也很快推出了自家的MCP能力。对国内团队来说项目本来就沉淀在蓝湖上让AI直接读蓝湖的标注数据省掉从设计稿到开发环境之间的人工搬运是相当实际的提效点。4.2 Playwright MCP给Agent装一双看得见的眼睛微软的playwright/mcp是我用的频率最高的MCP之一。它把浏览器自动化能力暴露成MCP工具Agent可以打开网页、点击按钮、输入文字、截图、读取页面DOM。效果相当于给大模型接上了一双手和眼睛不再是纸上谈兵。最典型的用法是配合编程Agent做端到端验证。以前写完功能要在浏览器里手动过一遍主流程现在让Agent先用Playwright MCP打开页面按测试用例操作一遍截图反馈问题。体验下来它能自动发现一些控制台报错和元素遮挡问题。易用性方面接入方式和自建Server一样在客户端配置里指向npx playwright/mcplatest即可。要注意的是它默认会启动一个带录制界面的浏览器这在本地调试很直观但在CI环境里记得要切换到无头模式别让浏览器进程卡住流水线。4.3 Blender MCP3D创作离AI也没有那么远Blender MCP是一个相对小众但很酷的方向。它把Blender的建模、材质、渲染操作包装成MCP工具AI可以通过Python脚本控制Blender场景。你用自然语言说创建一个半径为2的圆环并给一个镜面材质Agent就能驱动Blender完成操作。这类MCP比较适合有两个人群一是想快速搭场景草稿的3D从业者二是做程序化生成和教学演示的开发者。需要提醒的是3D软件的操作链路复杂AI出错后容易把场景弄得一团糟。我试的时候会先把Blender工程另存好再让AI操作反正撤销按钮在自动化里不太可靠做好备份是必要的。4.4 垂直场景自建数据库、文件系统、代码仓库除开这些知名场景MCP更大的价值在于你可以把内部系统也变成MCP Server。现在团队里最常自建的三类Server是数据库Server暴露query、get_schema、run_explain等工具让Agent在安全边界内执行只读SQL。文件系统Server按目录树读取、搜索、写入项目文件。代码仓库Server读取issue列表、修改代码、执行lint和测试命令。自建这些Server并不复杂本质上就是把你现有的内部API用MCP包一层。关键是提前想好权限边界哪些工具是只读的哪些允许写操作是否需要在调用链路上加人工审批。MCP本身是一个协议它不管你是不是好人权限设计得自己做。5. 实战中踩过的坑和排查技巧5.1 stdio进程起不来这是本地配置MCP时最高频的报错。现象是客户端里显示工具列表为空或者直接提示Server连接失败。排查路径有固定套路。第一步确认配置里的command用的是绝对路径尤其是Python虚拟环境的路径不要写python3这种依懒PATH的写法。第二步手动在终端跑一下Server脚本看有没有import错误。第三步MCP SDK提供了调试模式用mcp run --debug your-server.py启动日志里能看到完整的JSON-RPC通信过程报错更容易定位。我个人强烈建议所有Server在写业务逻辑之前先让tools/list能正确返回再一步步加能力。不然多个工具一起报错你很难分清是SDK问题还是业务代码问题。5.2 工具返回内容过大有些工具会返回很大的数据体比如数据库查询结果一次性给了十万行或者文件系统Server一次性读了一个巨型日志。模型上下文窗口是有限的结果太大不仅浪费token还会导致回答质量下降。解决方案有两个方向。一是Server端做好分页和裁剪比如只返回前50行再附一句还有N行未返回可通过参数偏移获取。二是用Resources替代Tools把大段内容以资源形式暴露让Agent有需要的时候再按需读取而不是在工具调用时一股脑塞回来。这里有个设计原则让工具返回决策所需的最小信息量而不是全部信息。模型做判断大部分时候只需要统计摘要和关键字段细节可以按需加载。5.3 权限和安全隐患MCP Server能干的事太多安全问题必须放在台面上说。一个文件系统MCP如果没有任何权限限制意味着Prompt注入一旦发生模型可能被诱导读取本机任意文件、执行任意命令这是真实存在的风险。我现在对MCP Server的安全基线有这么几条默认只读需要写操作的工具单独声明并加审批环节。工具入参必须做白名单校验比如路径参数检查是否在允许的目录范围内。敏感操作前二次确认尤其涉及执行命令、修改文件、生产环境数据。不要在一个Server里把所有工具都堆上去按最小权限拆成多个Server。5.4 Debug工具的优先级遇到MCP问题我一般按这个顺序排查用mcp run --debug启动Server看JSON-RPC通信是否正常。在客户端配置里把日志级别调到debug很多客户端能看到出错的原始报文。看工具描述和实际参数是否一致。模型调用失败很多时候是工具描述写得不够详细模型不知道该传什么参数。检查返回格式是否符合Schema预期尤其是返回类型为list或嵌套对象的情况。这套流程配合前面的几个注意点能解决九成以上MCP开发问题。6. 我对MCP的真实体会MCP不是一个玄学概念它就是一个很务实的标准化层跟当年TCP/IP统一网络、MQTT统一物联网消息一样属于越底层越有价值的协议。它不是万能药不会替你解决模型能力、业务逻辑、数据质量的问题但它确实把AI集成工具的最后一公里给捋顺了。我个人最大的体会是MCP的价值不只在调用几个现成工具而是逼着我们从开始就把模型和能力当两个独立模块来设计。工具的接口清晰了模型的角色边界明确了Agent项目才能往上叠加复杂度。往后的AI应用大概率会向MCP Server作为基础设施的方向演进提前把这块跑通等于给自己的技术栈加了一根通用管线。如果还没有实践过找个最小的需求比如接一个数据库查询慢慢加。等上手了你会发现AI应用集成的体验比API遍地开花的时代顺畅太多。