如果你最近在关注 AI 编程、Agent 自动化这些方向大概率绕不开“MCP”三个字母。MCP 全称 Model Context Protocol一句话解释就是给 AI 模型开一扇标准化的门让它可以读取外部工具的数据、调用外部工具的动作。上个月我刚做完一次跨栈 MCP 接入的开发任务整个过程从方案澄清到端到端验证差不多三周踩了不少坑也沉淀了一些确认有效的方法论这里完整复盘一下给后面要接 MCP 的同学减少点试错成本。这个任务的核心难点其实不在单个 MCP Server 怎么配而在“跨栈”两个字我们要同时打通设计侧的 MCP、浏览器调试侧的 MCP还有本地自动化测试侧的 MCP。每一层的数据模型、鉴权方式和工具语义都不一样要把它们串成一条链路还要保证最终端到端验证结果是可信的。对想搞清楚 MCP 是什么、怎么选型、怎么跑通完整验证流程的人来说这篇复盘可以当作一份实战参考而不是那种照着官方文档念一遍的教程。1. 项目背景与需求拆解为什么“跨栈”是 MCP 接入里最容易被低估的事1.1 这个项目到底在接什么先交代一下项目背景。我们团队维护一个前端中台里面沉淀了几十个业务组件和对应的设计规范、交互说明、视觉标注。业务目标很直接让研发同学用自然语言提问比如“帮我找一下搜索框组件的主题色规范”“这个按钮的 click 事件对应哪个接口”由 MCP 化的工具链自动从设计稿、代码仓库、接口文档里拉取上下文返回给大模型再由大模型给出结构化回答。所以整个接入工作分三条线并行推进设计侧接入 Figma MCP 和蓝湖 MCP让 Agent 能查询设计稿、图层结构、切图资源和标注信息。浏览器侧接入 Chrome DevTools MCP让 Agent 能实时获取页面 DOM、网络请求、控制台日志。自动化侧接入 Playwright MCP让 Agent 能自己打开页面、点击、输入、断言完成交互验证。每条线单独看都不复杂因为 MCP 生态里已经有官方或社区维护的 Server。但三线同时接入并打通问题立刻多起来MCP 协议本身是标准化的可每个 Server 返回的数据结构、鉴权方式、上下文格式都带着自己的“方言”跨栈组合时很容易互相冲突。1.2 跨栈到底跨在哪里如果把 MCP 接入理解成一个单向 API 调用那后面一定会吃苦头。跨栈场景下一次完整的 MCP 调用链路是这样的用户提问 → Agent 解析意图 → 设计侧 MCP 返回图层信息 → Agent 转成代码定位 → 浏览器侧 MCP 注入运行时上下文 → Playwright MCP 执行点击和断言 → 回传结果与大模型比对这里面每一层的数据语义都不同。设计稿的坐标体系是 px、图层结构是嵌套树浏览器里 DOM 的坐标系要经过视口缩放、devicePixelRatio、响应式断点多重映射自动化测试的选择器又是另一套语义。任何一环没对齐端到端验证就会挂但挂在哪里、为什么挂排查起来非常费劲——因为协议层没问题、单点功能也正常唯独串起来之后上下文对不上。这类问题没法靠搜索引擎直接找到现成答案必须自己把每一层的输入输出边界彻底理解清楚。这也是我把“方案澄清”放在整个项目第一优先级的原因。1.3 先搞懂 MCP 的四个核心概念在讲实操之前我觉得有必要快速过一遍 MCP 的概念骨架后面提到的工具选择、边界划分都建立在它上面。Client发起请求的一方通常是 AI 编程工具或自定义 Agent比如 Claude Code、Cursor、Codex 都内置了 MCP Client 能力。Server提供工具能力的服务端负责把外部系统的能力包装成标准接口。Tool一个可被模型调用的具体操作比如“获取文件”“读取设计稿节点”“点击页面元素”。Resource可被模型读取的上下文数据类似外部文件的抽象比如一份设计规范、一段日志。跨栈接入说白了就是同时挂载多个 Server让 Agent 在一个会话里能调不同来源的 Tool、读不同来源的 Resource。这个概念本身不难难的是多个来源同时存在时如何保证上下文不被污染、权限不被越界、语义保持一致。2. 方案澄清与选型先把 MCP Server 的边界画清楚2.1 MCP Server 不是越多越好项目启动时团队里有个直觉把市面上热门的 MCP Server 全接上一次到位图省事。但实际跑了两天就发现问题不断。首先是重复连接比如同时装了通用文件 MCP 和仓库专用 MCP两个 Server 对同一个路径都声明了访问权Agent 在选择工具时经常随机挑一个导致同一句话在不同轮次返回的结果不一致。其次是上下文膨胀每个 Server 的工具定义、资源描述都会注入到模型上下文里接得太多会把上下文窗口撑爆模型反而变得“迟钝”。所以第一步方案澄清其实是在做减法明确哪些 MCP 是刚需哪些是锦上添花。最终只保留了四类核心 ServerMCP Server解决什么问题必要程度Figma MCP / 蓝湖 MCP设计稿、标注、切图上下文必须Chrome DevTools MCP运行时页面 DOM、网络、控制台必须Playwright MCP自动化交互验证执行必须本地 MySQL MCP接口数据与业务数据上下文按需接入这里想补充一个观点MCP 接入的本质是“给 Agent 提供可信上下文”不是“展示你接了多少个工具”。宁可少接几个也要保证接进来的每个 Server 的数据质量可靠。2.2 跨栈接入必须画清的两个边界第一是“读”和“写”的边界。设计侧的 MCP 绝大多数是只读的Agent 只能查询浏览器侧和自动化侧的 MCP 是有写权限的比如 Playwright MCP 能真实点击按钮、提交表单。如果两类混在一起Agent 可能为了取一个样式值真的去点击生产环境的按钮这在安全上是不可接受的。我们的做法是把只读类 MCP 和可写类 MCP 拆到不同的 Client 会话通过会话级别切换来限制权限范围。第二是“现成 Server”和“自研薄层”的边界。MCP 生态再丰富很多工具也没法完全贴合内部数据格式。比如 Figma MCP 返回的是标准设计节点但我们的设计系统里有自定义 Token 命名规范直接拿原始数据让 Agent 判断它经常读错。最后我们写了一个很小的兼容转换层把公司内部样式描述转成 MCP Resource这件事虽然技术含量不高但对最终验证准确率的提升非常明显。2.3 Figma MCP 与蓝湖 MCP 的取舍很多人在社区问“Figma MCP 可以直接切图吗”这里说一下我的实测结论。Figma MCP 的能力边界取决于服务端暴露的方法列表官方访问令牌能取到文件结构、节点属性和图片导出链接所以获取切图资源链接是可行的但要注意它通常给的是一个导出接口地址Agent 还需要再发起一次请求才能真正拿到文件内容。“能不能直接切图”本质上取决于你的 Agent 工作流有没有把get-image这类工具串联起来。蓝湖 MCP 对国内团队更友好的一点是它的标注信息、切图资源、版本对照更贴近实际开发习惯。如果你的图稿管理在蓝湖我建议直接用蓝湖 MCP如果你维护的是 Figma 源文件那就用 Figma MCP。两边不要在同一个链路里重复接否则 Agent 经常拿到两份互相矛盾的“答案”反而增加噪音。2.4 浏览器侧和自动化侧怎么选浏览器侧我选 Chrome DevTools MCP主要原因是它和 Chrome 结合紧密能拿到真实页面的 DOM 快照、网络面板信息、控制台报错这样 Agent 可以在“设计稿上下文”之外多一个“运行时事实来源”。实际使用时要通过 Chrome 的远程调试端口调试后面实操部分会细说。自动化侧选 Playwright MCP图的是它交互能力强打开页面、点击、输入、等待元素、截图、断言一条龙。而且 Playwright 本身支持多浏览器后续要扩展兼容性测试也不用换工具。缺点是它的调用链比较长定位器稳定性会影响结果所以必须配套超时和重试策略。3. 实操实录从 MCP 配置到端到端验证3.1 搭建本地 MCP 客户端运行环境MCP 的运行模式主要有两种stdio 模式和 SSE/HTTP 模式。stdio 模式客户端直接拉起 Server 本地进程通过标准输入输出通信适合单机调试排查方便。SSE/HTTP 模式Server 部署在远端客户端通过 HTTP 连接适合多人共享、集中控制权限。我们的项目因为多人协作采用 HTTP 模式。配置层面以 Claude Code 的~/.claude.json为例接 HTTP 模式 Server 的配置大概是这样的{ mcpServers: { figma-mcp: { url: http://internal-mcp-server/v1/figma, headers: { Authorization: Bearer xxxxx } }, chrome-devtools-mcp: { url: http://internal-mcp-server/v1/devtools, headers: { Authorization: Bearer xxxxx } } } }有几个细节必须强调。鉴权 token 绝对不要写进公共配置仓库泄露一次代价极大建议用环境变量占位在启动时回填。HTTP 模式下的 Server 通常有超时配置如果 Agent 工具调用超过 30 秒客户端会直接报 timed out这个我们在后面排查专节会展开。3.2 打通设计侧 MCP把设计稿变成 Agent 能读懂的上下文Figma MCP 接入的核心动作有三个获取文件列表、读取节点树、提取样式和导出资源。实操时我先写了一个design-resolver工具输入一个设计稿链接解析出 fileKey 和 nodeId然后调 MCP 拿到节点信息再按公司的 Token 规范映射一次最终输出一份 Markdown 格式的“设计上下文”。为什么绕这么一圈因为 Agent 对结构化 JSON 的理解虽然不差但内容一多就容易遗漏关键字段给一份精炼摘要比丢一整棵 JSON 树可靠得多。这里分享第一个实战经验不要在 MCP Resource 里灌超过 50 个节点的完整信息。节点层级太深Agent 会迷茫验证阶段经常答非所问。后来我们限制默认只返回两层节点再通过追问的方式扩展子节点准确率提升非常明显。蓝湖 MCP 接入方式大同小异区别在于标注获取、切图下载、版本差异的接口路径不同。如果你的链路接的是蓝湖切记把“需求单号”和“设计版本号”作为上下文显式传给 Agent否则它默认取最新版但研发实际看的可能是上一版后面比对时容易做无用功。3.3 打通浏览器侧让 Agent 真正“看见”页面浏览器侧用 Chrome DevTools MCP通过 Chrome 的远程调试端口对接。启动 Chrome 时带上参数google-chrome --remote-debugging-port9222 --user-data-dir/tmp/chrome-mcp-profile这里有一条重要的安全提示调试端口一定不要绑到0.0.0.0只绑127.0.0.1否则局域网内其他设备也能连上你的调试端口等于是把整个浏览器页面 DOM 暴露在外。我见过有人图省事把服务放到容器里不加访问限制最后整个页面状态都能被外部读取这是非常严重的风险。打开调试端口后Chrome DevTools MCP 的 Server 会自动拿到可调试的 target 列表Agent 可以选择当前激活的页面做观察。连上之后最关键的是让 Agent 建立“设计稿坐标”到“真实页面坐标”的转换意识。比如设计稿上搜索框宽度是 320px但真实页面在 1440 布局下渲染成 280pxAgent 如果拿设计稿值直接写 Playwright 断言必然失败。我们专门加了一个取window.devicePixelRatio和布局视口的校正工具让 Agent 在断言前先确认真实渲染尺寸。3.4 Playwright MCP自动化验证的“手”Playwright MCP 解决的是 Agent 的“动手”能力它本身就是一个 MCP Server把 Playwright 的能力包装成可调用的工具。主要功能包括打开页面、输入文本、点击元素、等待状态、读取控制台、截图比对。我们的端到端验证流程最终跑通的样子是这样的用户提问“帮我验证注册页的邮箱输入框点击后是否出现红色校验提示且提示文字与设计稿一致。”Agent 先调 Figma MCP找到注册页设计稿里邮箱输入框的校验文案和颜色值。Agent 再调 Chrome DevTools MCP定位注册页面当前输入框的 DOM 位置和渲染状态。Agent 调 Playwright MCP打开页面、点击输入框、输入错误格式邮箱、点击提交。Playwright MCP 返回操作后的页面截图和控制台输出Agent 结合设计稿上下文做逐项比对。这个链路最考验人的是第五步的比对。Agent 的视觉能力确实能识别截图上有红色文字但具体色值是否与设计稿一致、字号差异有多大它靠“看”不一定准。我们最后加了一层元素级校验用 Playwright MCP 读取元素的计算样式把计算样式与设计 Token 做数值比对误差控制在 2px 或 2% 以内才判定通过。3.5 写一份端到端验证检查清单我习惯把串联流程固化成一张检查清单每接入一个新页面就照着走一遍避免漏测设计稿侧节点可以解析、Token 映射成功、切图资源可以导出运行时侧目标页面可访问、DOM 结构完整、关键元素能被正确定位自动化侧Playwright 可启动、选择器稳定、超时时间配置合理比对侧设计 Token 与计算样式映射完成、误差阈值定义明确安全侧写操作的作用域限制在当前测试环境绝对不允许触达生产环境这条清单里每一项单独拎出来都不难但串起来完整跑完一个新页面接入通常要半天到一天时间。不要小看这些琐碎步骤它们决定一条 MCP 链路能不能真正稳定地被业务使用。4. 踩过的坑与排查经验实录4.1 工具调用超时30 秒是个坎排查中最常见的问题是超时。很多 MCP Client 对工具调用都设置了时间上限比如 Codex 里默认是 30 秒。如果你的设计稿文件很大或者 Chrome DevTools MCP 在低性能机器上抓取完整 DOM 快照就很容易触发超时。我处理超时问题有三招给服务端加缓存把重复的 DOM 快照和设计稿解析结果缓存下来命中缓存时直接返回时间能压到毫秒级限制返回体大小DevTools MCP 配置里只返回外层节点忽略脚本内容、样式内容和超大属性对确实耗时的工具把客户端超时时间显式调大到 60 秒但只对个别工具放开不能全局放开。还有一个容易忽略的细节超时不一定发生在 Server 处理过程中也可能发生在 Agent 接收数据的阶段。有些 MCP Client 在响应体超过一定大小时会拒绝解析同样表现成 timed out。排查时可以打开服务端日志看任务在哪个阶段消耗了多少时间对症下药。4.2 上下文串味多个 Server 的 Resource 互相污染我们遇到过一种很诡异的情况同一句提问先问设计稿再问页面状态Agent 会把设计稿里的 “error” 文案当成页面里真实出现的错误给出完全错误的结论。原因并不复杂多个 MCP Server 的 Resource 都注入到了同一个会话里Agent 没有严格的“第一手来源”意识。解决办法是在工具描述里强制加入来源字段例如resource: design-only并且让 Agent 在推理时先声明信息来源。后来我们又加了一条提示词约束任何结论必须引用 MCP 返回中的source字段。虽然不能 100% 消除误判但效果明显可信度提升了一个台阶。4.3 权限边界没设好差点误操作生产数据这就是前文说的读写边界问题。有次联调时Agent 为了验证一个下拉框的配置直接调了 Playwright MCP 在生产环境页面点了提交按钮。还好那个接口有二次确认没有造成实际数据影响但把整个团队吓得够呛。从那以后我们定了一个铁律任何带写操作的 MCP Server在配置里必须指定隔离环境。如果 Agent 拿到的目标 URL 不是测试环境域名直接拒绝执行。实现方式是在 Playwright MCP 外层加一个代理网关校验目标 URL 的 host 是否在白名单内不在就直接返回错误提示从源头阻断误操作。4.4 同一 Server 重复连接导致状态不一致还有一种坑同一个 MCP Server 被多个 Client 同时连接本地装了一份、CI 里又挂了一份两边配置还不一致结果设计稿连接经常报 401。排查思路其实很简单。先看 MCP 配置里的 JSON-RPC 请求确认 endpoint 是不是同一个然后看鉴权 token 是否一致。如果是 HTTP 模式建议在 Server 端做连接复用不要让每个 Agent 进程都新建独立会话。连接数一多状态管理容易出各种奇怪问题。4.5 常见问题速查表现象可能原因快速处理工具调用 30 秒超时Server 处理慢或响应体过大加缓存、限制返回体、单独放开超时Agent 答非所问Resource 上下文污染增加来源字段限制注入数据量拿到 401token 不一致或多端重复连接核对配置、统一鉴权服务点击到了生产环境写权限边界未设加域名白名单代理拒绝非测试环境设计稿坐标对不上未考虑视口缩放和响应式增加 devicePixelRatio 与布局视口校正切图取不到二进制MCP 只返回导出地址工作流里补充文件下载工具这张表是我们内部排查时的速查手册基本覆盖了跨栈接入百分之八十的问题。5. 复盘与个人体会5.1 端到端验证的本质是“语义对齐”不是“接口跑通”这个项目做下来我最大的体会是端到端验证的意义不在于“有返回值”或者“调用不报错”而在于整条链路的数据语义一致。设计稿里叫primary-button的 Token代码里叫btn-primaryPlaywright 选择器里叫button[data-testidsubmit]这三者的对齐才是跨栈接入的真正难点。MCP 协议只是水管真正难的是让水管里流动的液体成分保持一致。我强烈建议在接入 MCP 之前先把团队内部已有的命名术语整理成一份术语表让 Agent 在构建上下文时直接使用术语表而不是从零猜。这件事投入产出比极高能省掉后面大量的排查时间。5.2 验证要从“最小闭环”开始不要一上来就搭五六个工具串成的复杂链路。我通常先把最小闭环跑通只接一个设计侧 MCP用一个简单问题验证“设计稿查询 — 返回上下文 — 大模型回答”能通通了之后再加入 DevTools最后才接 Playwright。每加一层都保留上一层的测试用例这样定位问题的时间可以缩短一半以上。5.3 最后再分享一个小技巧最后分享一个很有用的调试习惯在 MCP Client 的调试日志里把 JSON-RPC 的请求与响应完整打开一次你会立刻看到每个工具被调用时的入参、返回体大小和耗时。这个输出量确实很大但在跨栈排查时极其好用。尤其当 Agent 回答出错时你能直接看到它调了哪个 Server、传了什么参数、拿到了什么数据错在哪里一目了然。等到链路稳定再把日志级别调回 info避免日志刷屏。这次经历做下来我的收获不是学会了配置多少个 MCP Server而是真正理解了一件事MCP 把工具使用能力标准化了但标准化的是“管道”不是“数据”。一个跨栈 MCP 链路能不能稳定可用最终取决于每一层数据语义的对齐和工程化落地。希望这篇复盘能帮你少走几步弯路。
