1. 需求澄清接 MCP 不是为了追热点是为了解决链路断点先说项目背景。团队做的是一个跨境电商的内部运营中台日常有大量跨系统操作运营要看设计稿、要调接口数据、要查订单库、要盯线上页面表现。很多重复劳动本质上是在几个工具之间搬运信息——从 Figma 里拿切图标注从 Chrome DevTools 里看页面 DOM 结构从 MySQL 里查商品状态再回到后台系统里改配置。MCPModel Context Protocol在圈子里火了之后老板和技术负责人第一反应都是我们也要接。但当时我们接 MCP 的真实诉求并不是要给客户提供一个MCP 功能而是想解决一个具体痛点让内部的 Agent 应用基于大模型的任务助手不再只是能聊天而是能干活——把跨栈的信息链路自动串起来。这个诉求翻译一下其实就是三句话让 Agent 能安全访问浏览器页面并读取实时状态让 Agent 能读懂设计稿里的关键标注和切图信息让 Agent 能把上述信息和后端业务数据订单、库存关联输出可执行的操作建议。1.1 初始需求里最容易被忽略的一句话需求评审会上产品同学提了一句很有迷惑性的话就接三个 MCP一个浏览器控制一个设计稿读取一个数据库查询应该很快吧。这句话听上去简单实际上埋着一个大坑这三个接入分布在完全不同的技术栈上。浏览器控制涉及本地进程管理和 CDPChrome DevTools Protocol设计稿读取涉及第三方平台开放 API 的鉴权数据库查询涉及内网安全和读写权限控制。每个单独拿出来都不难但串成一条链路之后出了问题很难定位是哪一段断的。我们后来做澄清时把所有需求拆成了四层才算把范围彻底厘清层级内容验收标准工具层MCP Server 能正确 exposes 工具tools每个工具的 schema 描述准确参数可校验连接层Agent 客户端能发现工具、调用工具、拿到结构化结果往返延迟、错误信息可读业务层Agent 能利用工具完成指定任务如查XS号连衣裙最近30天库存变化输出的结论与人工核对一致安全层权限、鉴权、操作审计闭环无越权调用操作留痕这一澄清的收益很大。因为如果只停留在第一层Demo 很容易跑通但真正上线后 Agent 调用数据库的权限边界、设计稿 token 的存储方式、浏览器操作的回滚机制全都得重做。所以我的第一个建议是遇到接 MCP这种听起来很轻的需求先往深挖一层的隐藏依赖再动手。MCP 本身是协议协议不难难的是协议背后你要暴露什么资产、给谁用、怎么控制风险。1.2 把接入 MCP翻译成可验收的技术需求澄清阶段的产出不是一份需求文档而是三个可检验的技术结论一个是工具边界。哪些能力应该封装成 MCP 工具哪些能力应该留在 Agent 内部逻辑里。比如打开浏览器访问某页面这个动作应该是浏览器 MCP Server 提供的工具。但根据设计稿标注自动生成商品图片的 alt 文案这是 Agent 自己的业务推理不应该下沉到 Server 端。边界不清会导致 Server 越做越重变成业务逻辑的大杂烩。一个是运行形态。MCP Server 是本地进程、远程服务还是运行在网关后面直接决定了鉴权和网络策略。我们最后选择了本地/远程混合浏览器控制和数据库查询走本地网络设计稿读取走远程 API在线服务统一通过一个 MCP 网关暴露给 Agent。网关的意义是让 Agent 客户端只认一个 endpoint不需要关心底层三个 Server 的差异。一个是数据结构。数据库查询返回的是原始行记录设计稿返回的是画布节点信息浏览器返回的是 DOM 快照。这三者的 schema 如果不统一Agent 很难把它们关联起来。我们在 Server 端做了一层轻量的结果标准化凡是查询类工具统一返回{ status, summary, data, meta }凡是操作类工具统一返回{ status, action, result, index }。这个设计在后面端到端验证中起了大作用。这轮澄清花了两个半天代码一行没写。但事后看这一步其实是整个项目最值钱的部分。2. 方案分叉跨栈接入时的 Server 选型与 Client 接入抉择澄清完需求就到了技术分叉点。市面上 MCP Server 组件很多——Playwright MCP、Chrome DevTools MCP、Figma MCP、蓝湖 MCP、各种数据库 MCP 都有现成的开源方案。当时我们面临一个选择全盘用开源组件还是自己写这个问题不能拍脑袋要对照项目边界来选。2.1 浏览器控制用 Playwright MCP 还是自研 CDP 服务浏览器控制是整个项目里最早定的环节。我们对比了两条路线路线 A直接用 Playwright MCP Server官方提供的playwright/mcp好处是开箱即用browser 工具、page 操作、快照截图全都有路线 B基于 CDP 自研一个最小化的 browser MCP Server只暴露我们需要的 3~4 个工具navigate、get_page_snapshot、click_element、extract_text。选路线 A 的理由很充分Playwright MCP 的覆盖面广、Schema 设计成熟遇到浏览器版本差异有社区兜底。但用的时候要特别注意它的运行方式——它默认开启的是本地调试端口所有工具调用会直接在真实浏览器上执行。这对人机协同场景没问题但如果是生产环境里 Agent 无人值守地操作页面就必须额外加一层允许操作的范围控制。我们的做法是包了一层白名单只允许导航到业务配置的域名列表防止 Agent 被 prompt 诱导访问外网地址。这算是 Playwright MCP 使用中没有写在文档里的细节。浏览器类 MCP 工具本质上是能打开浏览器的人的权限接入前先想清楚这个工具要给 Agent 多大的行动自由度。2.2 设计稿读取方案与代价设计稿读取这一路可选项更杂。Figma MCP、蓝湖 MCP 都有对应生态但这里有个要命的前提我们团队用的是蓝湖而设计稿数据并不全在蓝湖上部分老项目的历史设计稿存在本地的 Sketch 文件里。要把这些全部统一进 MCP 工具的话最终呈现的服务是一个混合数据源的设计稿 MCP Server远程源走蓝湖开放 API读标注、切图、下载资源本地源读公司内部的素材管理系统按项目 ID 找文件。这个 Server 只暴露两个工具search_design按关键词找设计稿和get_design_spec取某设计稿的标注详情。所有数据源差异都被封装在 Server 内部Agent 不需要知道每个设计稿存在哪。当时有人提过要不要干脆用 Figma 替代蓝湖统一生态。这个建议被否了因为迁移成本太高——历史设计稿、团队协作习惯、插件依赖都绑在蓝湖上。做跨栈接入切忌为了统一而统一最好是用一个统一入口去适配多个数据源而不是强行让业务迁到一个平台上。2.3 数据库查询最小的暴露面数据库查询这条线争议最大。技术角度做一个通用 SQL MCP Server 很容易但风险也最大——一旦 Agent 被诱导执行DROP之类的危险语句或者查出敏感订单数据责任归属很难扯清。我们的取舍是不做通用 SQL 工具只做业务专用查询工具。也就是说MCP Server 不暴露执行任意 SQL的能力而是暴露query_order_summary、query_inventory_by_sku之类的高层函数内部用模板化的 SQL 实现参数只能传 SKU、时间范围这些白名单字段。这样 Agent 能拿到它需要的业务数据但拿不到information_schema也执行不了写操作。代价是如果后续要支持新查询需要额外在 Server 端加一个工具做 Review。对内部系统来说这个代价完全可以接受。经验小结跨栈接入时Server 的选型逻辑不是哪个功能全选哪个而是哪个暴露面最小且满足需求就选哪个。功能全的组件往往权限大、约束少直接接入会放大风险。3. 实施过程里真正耗时的四个拦路虎方案定了进入实施期。实现 MCP Server 本身的代码量不大但我们在实际联调中遇到四个问题每一个都让项目卡了一到两天。这里详细拆解都是可以直接复用的经验。3.1 超时Agent 端 30 秒超时的真相我们内部 Agent 客户端用的是标准 MCP SDK调用远程工具时有一个默认超时设定请求发出后 30 秒没返回就报 timeout。最初验证时数据库查询和浏览器导航都能在几秒内返回没当回事。后来测到一个真实场景——Agent 需要同时查询 30 个 SKU 的库存工具内部循环查库加汇总跑一次要 40 多秒结果客户端直接超时。超时问题的排查链路是这样的先看 Server 日志确认 Server 侧实际执行了多久 —— 40 秒以上再看 Agent 日志发现报错是MCP client request timed out after 30000ms最后才发现工具功能正常但调用超时和工具本身报错在日志里被混在一起了。修复方案不复杂一个是给工具的执行逻辑加合理的分批比如每批最多查 10 个 SKU另一个是给 MCP Server 的call_tool接口加一个progress回调长任务先返回一个任务开始的中间状态避免客户端一直干等。如果用的 MCP SDK 不支持流式进度最简单可靠的办法是控制单次工具调用的数据规模宁可让 Agent 多调几次也不要让单次调用跑 30 秒以上。这一条值得所有接 MCP 的同学记下来MCP Server 要主动适配客户端的超时机制不是我的工具能跑通就行而是我的工具要在调用方的超时窗口内跑完或者有明确的进度推进机制。3.2 鉴权从本机玩具到跨栈调用的权限断层早期验证 MCP 时大家普遍是本地跑一个 Python 脚本直接初始化 MCP Client 连接本地 Server不涉及鉴权Secure 得很。但当多个服务跑在同一个内网网关上、Agent 对所有 Server 统一下发令牌时问题就来了。我们遇到的具体情况设计稿 MCP Server 调用蓝湖开放 API 需要一个lanhu_token这个 token 存在 Server 的配置文件里数据库 MCP Server 查询用的是一组内网数据库账号密码存在另一个配置文件里。Agent 客户端在调用这两个工具时只需要传自己的 Agent API Key。这中间就有一个权限断层Agent 只要能访问网关就能调用所有 Server 的所有工具包括数据库查询。一旦 Agent 被恶意 prompt 诱导就可能通过数据库工具把全量订单数据拉走。我们的修法是三层鉴权第一层Agent 与网关之间用 API Key 确认调用者身份第二层网关到 Server每个 Server 维护一份允许调用哪些工具的细粒度 ACL例如数据库 Server 只允许query_order_summary、query_inventory_by_sku两个工具其余工具拒绝第三层Server 内部再校验参数比如数据库查询里的 SKU 列表一次最多传 20 个防止批量拉取。这套做完之后才敢让 Agent 在生产环境跑。MCP 的鉴权没有一个统一标准但原则是相通的每个工具都要有 owner每个调用都要有身份每个数据访问都要有边界。3.3 日志Server 端日志的正确管理方式很多开源的 MCP Server 只做了控制台输出没有提供结构化日志的配置项。联调的时候一旦 Agent 调用报错我们只能去翻 stdout有时一次调用有几十行喷出来根本看不出是工具抛错还是 Agent 决策错误。这里我强烈建议在 MCP Server 里集成一套自定义日志管理按照统一格式输出[timestamp] [level] [tool_name] [session_id] [request_id] message其中 session_id 来自 Agent 调用上下文request_id 由 Server 生成并透传给下游。这样排查问题的时候可以用 session_id 串联Agent 说了什么 - 调了什么工具 - 工具返回了什么 - 为什么这么返回这一整条链路。我们的日志体系分三层标准日志记录每一次工具调用的入参与出参脱敏后审计日志记录谁在什么时间调了什么工具用于安全合规状态日志记录 Server 自身的启停、异常、API 调用失败等生命周期事件。这套日志体系在后来的端到端验证中帮了大忙——定位一个Agent 拿到正确数据但给出错误结论的案例时通过对比工具返回值和 Agent 上下文很快确认是 Agent 解析 JSON 时漏了字段而不是数据源出错。3.4 空参数一个无伤大雅却让流程卡死的细节实施过程中最小的坑反而最耗时间。MCP Server 的每个工具都定义了输入参数 schema但框架本身不会强制检查哪些参数必填、哪些可选。我们有一个工具search_design参数是keyword可选如果 Agent 调用时没传 keyword工具应该返回最近修改的 N 个设计稿。但我们的 Server 实现里直接写if keyword is not None去查库没传时就返回空列表。这个问题的可怕之处在于工具本身不报错返回的是一个合法的空结果。Agent 拿到空列表后会非常认真地告诉用户没有找到设计稿。这完全是一个假阴性错误用户不知情Agent 也不知情只有人工复核才能发现。修法很简单在工具入口处加一个统一的参数校验层必填参数缺失直接返回明确错误可选参数缺失则走默认逻辑并且把本次使用了默认逻辑写进返回的meta字段里。这样 Agent 至少知道搜索条件被放宽了。这个实践告诉我们别把参数校验的职责丢给大模型模型再聪明也猜不到你要的是哪套默认行为。工具契约要定义到每一个字段为空时怎么办的程度。4. 端到端验证不能只验证接口通要验证流程通做 MCP 接入最虚的一步是验证环节。我见过很多团队 demo 的时候拿一个预先写好的输入试一遍工具返回正常就宣称接入成功。但真正上线跑一次完整业务流程立刻露馅工具各自都通串起来处处断。我们这次的端到端验证做了三层设计供大家参考。4.1 验证金字塔三层设计第一层是单工具验证。每个 MCP 工具单独调一遍确认 schema 正确、入参校验生效、返回结构与文档一致。这层主要靠脚本来做跑几十个典型场景。第二层是多工具串联验证。构造几个典型业务任务要求 Agent 必须依次调用多个工具才能完成。比如任务查商品 XS23223 对应的设计稿里的主图标注再看看这个商品最近15天的库存趋势最后根据库存是否低于安全线给出补货建议。这个任务里Agent 至少需要调用search_design-get_design_spec-query_inventory_by_sku三个工具且工具之间的数据要能对上号——设计稿里的商品编号和数据库里的 SKU 是同一个值Agent 才能串联。这个验证的目的不是测工具而是测上下文连贯性。第三层是异常路径验证。故意给 Agent 布置一些容易失败的场景请求一个不存在的 SKU、访问一个无权限的设计稿、浏览器导航到一个已下线的页面、数据库查询超时。重点观察 Agent 能不能识别异常并把正确的错误信息反馈给用户而不是编造一个看似合理的答案。我们还专门测了Agent 面对空结果时的表现这和我们前面提到的空参数坑是配套的。4.2 五条关键验证路径在业务上我们细化了五条核心验证路径覆盖了绝大多数真实使用场景路径涉及工具验证重点设计稿检索与标注读取search_design、get_design_spec数据源切换时结果一致性页面浏览与元素定位navigate、get_page_snapshot、click_elementDOM 变更后 Agent 能否自适应商品库存查询与异常告警query_order_summary、query_inventory_by_sku数据准确性、参数边界跨域任务串联全部Agent 上下文记忆、工具选择顺序安全路径全部越权访问是否被拒绝、审计日志是否完备每条路径跑完后我们都会把 Agent 的输出和人工核对结果做比对。一开始有不少偏差比如 Agent 把近15天理解为最近15个自然日还是从今天往前数15天这类语义问题。这些偏差在单工具验证阶段根本不可能发现只有放在业务流程里才会暴露。4.3 用失败的验证发现设计遗漏整个验证阶段最有价值的一次失败是跨域任务串联里 Agent 给出的补货建议完全错了。复盘过程很有意思Agent 查询库存正常、查询设计稿正常但在生成建议时它没有参考该商品在设计中标注的卖点优先级只基于库存数字就给了一个建议补货 500 件的结论。后来我们看日志才发现get_design_spec返回的数据里其实有卖点标注但 Agent 没有把它作为决策依据——因为这个字段在返回结构里藏在data.specs深层而 Agent 的 prompt 只描述了读取设计稿标注没有描述这个标注要用于库存决策。这个问题的根因不在 MCP 工具而在于Agent 的任务编排层对工具输出的利用不够明确。但它给我们的启示是端到端验证不只是验证 MCP Server 稳不稳更重要的是验证MCP 工具接口设计和 Agent 使用方式是否匹配。如果工具返回的数据结构过于抽象Agent 很难自觉地进行领域推理。我们最终的做法是调整get_design_spec返回结构把卖点和主图这两个字段提升到顶层并在工具描述里写了此结果可用于补货决策分析、文案生成等场景。这样不亚于给 Agent 装了行业经验它拿到结果后更清楚该怎么用。5. 复盘总结这次跨栈 MCP 接入最值得带回的教训整个项目从澄清、选型、实施到端到端验证前后花了近三周。按代码量算MCP Server 本身的实现只占了两天工作量剩下大部分时间都花在需求澄清、权限设计、日志治理、验证路径打磨这些事情上。这让我重新认识了 MCP 接入的本质——它不是一个写几个工具函数的开发任务而是一个把内部能力安全、规范地开放给 AI 使用的架构任务。5.1 方案澄清比写代码重要接 MCP 之前先花足够时间回答几个问题谁调用这些工具调用范围是什么失败时怎么兜底工具返回的数据给谁看跨栈接入中数据源只要超过两个就必须为每个数据源定义统一的返回结构、错误码、日志格式否则 Agent 一端要处理 N 种异常结构逻辑复杂度会成倍上升。我现在回头看如果最初直接引用 Playwright MCP、蓝湖 MCP、通用 SQL MCP可能三天就能跑通 demo。但那样的系统没有服务边界、没有数据约束、没有操作留痕上了生产环境基本是事故现场。宁可慢一点先把边界和约束谈清楚。5.2 跨栈的本质是职责边界跨栈不是说一个 Server 什么能力都有而是每个 Server 专注于自己的领域对外暴露的工具要小而明确。我们的浏览器 Server 只做页面操作、设计稿 Server 只做信息检索、数据库 Server 只做只读查询。每个 Server 都能独立演进、独立发布、独立负责人。如果整个跨栈能力揉在一个巨型 Server 里任何一个数据源升级都会牵动全局。这一点在热词里也频繁出现——Playwright MCP、Chrome DevTools MCP、蓝湖 MCP、Figma MCP本质上都是领域职责的切片。选型时要做的是把这些切片接进来然后在一个网关层做统一治理。5.3 端到端验证的度验证不能只测正常流程通还要测异常流程不崩和结果可解释。我们最后加了一条好习惯每个工具返回的结构里都带着meta字段描述这次查询的数据源、执行时长、是否使用了默认参数。这让 Agent 出错时我们能快速区分是数据源问题、编排问题还是Agent 理解问题。如果今后有人让我给一个最直接的 MCP 接入建议我大概率会说先定义好日志里能看见什么。只要工具调用链路是透明的所有问题都能在分钟内定位否则再炫酷的 MCP 集成也只会在问题爆发时变成一无所知的盲盒。这次项目最终交付的不只是几个 MCP Server而是一套AI 工具开放的标准姿势后续新接数据源都是照这个流程走。