1. 这次跨栈接入的起点方案澄清为什么值得单独立项接到这个活儿的时候需求原文只有一句话把 MCP 接入一下让 Agent 能干活。 没说清谁是 Agent也没说清接哪个系统更没说清干活是指查数据、跑流程还是改文件。当时团队里正好有人刚在后端服务里跑通了一个 MCP server觉得这不就是一个协议嘛调通就走结果真往下拆的时候才发现单点 demo 和跨栈接入之间的距离差不多是拿 Postman 调了个接口和上线一套带鉴权、限流、可观测的网关服务之间的距离。先说清楚我这里说的跨栈是什么。MCPModel Context Protocol本身解决的是大模型应用和外部工具之间怎么标准化地连接的问题它定义了一套 JSON-RPC 风格的消息格式让客户端比如 Claude Code、Cursor、Codex、自研 Agent可以动态发现服务端暴露的工具并调用。但跨栈接入意味着你的 MCP server 不止要连一个东西而是要在一条实际业务流程里同时对接设计稿平台、浏览器自动化工具、IDE 插件、本地 CLI 甚至逆向分析工具。拿我们这次的实际场景举例最终链路上游是蓝湖 MCP 和 Figma MCP 拉设计稿信息中游是 Playwright MCP、Chrome DevTools MCP 做页面定位和交互验证下游还要接到自研的部署脚本和数据分析模块中间可能穿插 Burpsuite MCP、IDA MCP 这类安全分析工具做异常排查。每个栈都有自己的运行时、身份体系、数据格式和调用方式MCP 只是把调用这层统一了但对话背后的坐标体系、权限模型、超时语义、返回数据大小全部都要你自己消化。所以我把整个项目切成了三块方案澄清、服务端落地、端到端验证。方案澄清排在最前面不是因为它流程上先到而是因为跨栈项目里 80% 的返工都死在边界没定清楚。什么算 MCP server 的职责什么算客户端策略什么算业务系统自己的逻辑这三件事一开始不掰扯干净后面每接一个新栈都会把前面推倒重来一遍。2. 方案澄清阶段三个必须定下来再动手的问题2.1 能力边界哪些工具暴露给 Agent哪些留在白名单MCP 的工具列表可以做得非常宽松也可以做得非常克制。宽松的做法是把服务端能调用的函数全部映射成 tools让 Agent 自己挑。听起来很灵活实际跑起来会出两个问题一是工具命名和 schema 一多模型做 tool selection 的准确率直线下降经常选错工具二是安全不可控任何能触达生产的工具都不该裸奔着暴露给一个可能产生幻觉的模型。我们当时的做法是给每个接入的系统建一个能力清单只暴露三类工具只读查询类、强校验写入类、高权限人工确认类。只读类比如从蓝湖拉取画板标注、从 Figma 获取图层样式、用 Chrome DevTools 抓当前页面性能数据这类是 Agent 的主力工具。强校验写入类比如触发一个部署流水线必须带环境、版本号、回滚策略三个参数服务端还会再校验一次白名单。高权限类比如执行数据库变更、修改生产配置这类工具默认不启用要用的话得在配置里显式打开而且调用前会走一个额外的审批回调。这里有一个很容易踩的误区很多人以为 MCP 的服务端把工具暴露出来就完事了实际上客户端本身也有策略层。同一个 MCP server接到 Claude Code 上和接到自研 Agent 上行为差别很大。像 Codex 这类偏 IDE 场景的客户端对工具返回结果的格式要求更严格你返回一大段 Markdown 它照样能被塞进上下文但塞进去之后模型可能就分不清哪些是工具结果、哪些是历史对话。所以方案里必须写清楚哪些约束在服务端做哪些约束在客户端做避免两头都以为对方兜底最后谁都没管。2.2 传输与环境从 stdio 到 SSE客户端形态决定方案MCP 协议目前主流两种传输方式stdio 和基于 HTTP 的 SSE / Streamable HTTP。stdio 适合客户端和服务端在同一台机器上的场景比如本地跑一个 Python 脚本作为 MCP serverCursor 直接 launch 一个子进程通过标准输入输出通信。SSE 则适合远程部署、多客户端复用同一个服务端的场景服务端是一个常驻 HTTP 服务客户端通过 URL 建立连接服务端通过 SSE 主动推送事件。这次跨栈接入里最麻烦的是不同客户端支持的传输方式不一样。像 Claude Code 和自研 Agent 对 SSE 支持得比较成熟但有些 IDE 插件只支持 stdio或者对自定义 SSE header 有特殊要求。我们在方案澄清期就拉了一张矩阵表把每个客户端的传输能力、鉴权方式、超时限制都列出来再决定服务端到底提供几种传输入口。最后结论是核心 server 提供 SSE 为主同时保留一个 stdio 启动器让本地调试场景可以直接拉起子进程。这个决策后面联调时帮了大忙因为很多诡异问题在 stdio 模式下很好复现切到 SSE 就多了一层网络排查的成本。另外还要定清楚环境隔离。MCP server 连接的是设计稿平台、浏览器工具、部署系统这些系统本身有 dev、staging、prod 环境。Agent 在开发环境跑的流程和在生产环境跑的流程绝不能共用一个 MCP 服务端实例。我们在配置里用环境变量区分 server 的目标环境并且要求每个环境内的工具能力保持一致这样端到端验证时才能保证开发环境跑通 生产环境大概率跑通。2.3 身份鉴权与审计MCP 接入里最容易忽略的安全环节MCP 协议本身对鉴权的定义留了很大的自由空间规范里没有强制要求服务端怎么校验调用者是谁。如果你只是本地起一个 stdio 服务那确实不用考虑进程本身是用户自己拉起的。但一旦走 SSE 暴露到服务器上身份问题就立刻冒出来。我们的方案里规定MCP server 必须对接统一的内部身份系统客户端调用时在 header 里携带服务注册时下发的 token服务端在进入工具分发逻辑之前先做身份解析和权限判断。这一步看着简单实际操作时有几个细节特别容易被忽略。首先是工具级权限不是登录了就什么都能调要按人和Agent 任务两个维度做交叉授权。其次是审计日志谁在什么时间调了哪个工具、传了什么参数、返回了多大结果这些都要落库。MCP 接入最大的隐形风险是它把原来需要人手工完成的高风险操作变成了模型一条指令就能触发的自动化操作中间少了很多人为确认关卡审计日志是事后回溯的唯一抓手。我们甚至在方案里约定所有写操作的工具名统一带上 apply / execute / run 前缀只读工具带 get / list / search 前缀这样从日志里就能快速区分请求性质。这个阶段还有一个很值得聊的判断原生的蓝湖 MCP、Figma MCP 基本都是官方的 server它们鉴权方式通常是走平台自身的 token接入成本低但你能拿到什么能力、返回什么字段完全取决于官方实现。而自研 MCP server 的好处是可以按业务语义定制工具比如把从设计稿提取某个按钮的圆角值和颜色封装成一个工具而不是让 Agent 自己去拼图层接口。方案澄清阶段要明确哪些栈用官方 server哪些栈值得自研原则是跨系统数据转换逻辑多的自研只是单一平台内读取的用官方的。3. 服务端落地细节从零实现一个可用的 MCP Server3.1 Server 骨架和工作流设计我这次服务端用的是 Python 官方的 MCP SDK整体结构不算复杂一个 transport 层负责处理 stdio / SSE 连接一个 registry 层维护工具列表一个 dispatcher 层根据工具名分发到具体的业务实现。写代码之前先画了调用链路一条工具调用的完整生命周期是客户端发 initialize 请求服务端回协议版本和能力信息客户端再发 tools/list 拿工具清单之后每次调工具都是 notifications/tools/called 和 tools/call 的配对服务端执行完业务逻辑之后把结果包装成 structured content 返回。这里面最不值得低估的是 initialize 阶段。你以为它只是握手实际它决定了后面所有行为是否正确。协议版本不匹配会出现什么情况客户端和服务端都认为自己是对的然后互相等待最后超时。我们遇到过一次客户端声称支持 tools/list 的某种 filter 能力服务端老版本 SDK 没实现结果客户端拿到完整工具列表后乱猜参数连续报错。后来我把协议版本和 SDK 版本的兼容性矩阵贴在 README 里每次升级 SDK 都要跑一遍全链路验证不再只看调用通没通。工作流设计上还有一个被反复提起但经常做反的点MCP server 到底应该做成薄适配层还是厚业务层。我的建议是薄适配层。MCP server 只做协议转换、参数校验、结果标准化真正的业务逻辑留在后面的基础服务里。这样做的直接好处是业务逻辑可以被非 MCP 渠道复用MCP 只是其中一个调用入口而不是把 MCP 和业务死死绑在一起。后面接新客户端的时候只需要保证协议层兼容业务层完全不用动。3.2 工具 schema给 Agent 一个清晰、最小、可验证的工具面MCP 的工具调用依赖 JSON Schema 描述输入参数这段 schema 质量直接决定模型能不能准确填参。我们的实践经验是schema 要遵循三个原则参数数量少、描述里带枚举约束、必填项显式标出来。参数数量这块单个工具的参数上限我们控制在 6 个以内。超过 6 个模型在函数调用时的 field mapping 准确率会肉眼可见地下降尤其是多字段名相似的时候比如 fromDate 和 startDate模型真的会填混。所以能拆成两步的不要硬塞一步能用一个查询条件对象收敛的字段就先用对象包一层。描述里带枚举约束的意思是如果某个参数只接受dev / staging / prod三个值直接在 description 里写清楚模型看到之后基本不会再传 production 这种别名。必填项标出来这个看着是基本功但很多手写 schema 的人会漏漏了之后模型会有两种表现一种是所有参数都传不管必不必填另一种是能省则省导致服务端校验失败。无论哪种都会增加一整个来回的无效交互。工具返回格式我们统一用 JSON 加一层 content 包装MCP 允许返回文本、图片、资源链接等类型。这里有个跨栈经验如果工具要返回设计稿截图或者浏览器截图不要直接把 base64 图片塞回给模型token 消耗会直接爆掉。正确做法是返回一个可访问的对象存储 URL并把图片的关键信息尺寸、坐标、色彩值列表用结构化文本同时返回这样模型既能理解内容又不会被迫吞掉一张大图。3.3 日志与自定义日志管理调试跨栈问题的基础设施MCP server 的日志管理容易被当成小事实际联调时它往往是救命稻草。官方 SDK 默认的日志输出在 stdio 模式下会和协议消息混在同一个标准输出流里一旦打印了无关内容客户端解析协议就会出错这是个非常隐蔽的坑。我们这边自己封装了一个日志模块按协议日志和业务日志完全分离协议日志走文件记录每次 initialize、tools/list、tools/call 的原始报文业务日志走标准结构化输出记录工具执行耗时、参数摘要、返回体大小。一开始我还担心日志打太细会影响性能后来用下来发现完全多虑了。MCP server 的核心瓶颈在工具本身的计算和外部 API 调用日志写入的开销几乎可以忽略。真正麻烦的是日志格式不统一。有的模块输出 JSON有的输出纯文本排查问题的时候 grep 都 grep 不出来。后来我统一了字段规范timestamp、request_id、session_id、tool_name、status、duration_ms、params_summary、error_msg一个请求从进来到出去的完整链路都能串起来。设置里还留了一个 debug 开关线上默认关排查问题的时候动态打开能看到每一步协议交互的细节。4. 联调踩坑记录超时、上下文与跨平台差异4.1 Codex 客户端 30 秒超时问题联调过程中最典型的一个坑来自 Codex 类客户端对 MCP 调用的超时限制。当时我们有一个工具需要拉取一个跨系统报表正常情况 5 秒能返回但数据量大的时候要跑 30 秒往上。单测通过手动 curl 调用也通过结果一接到 Codex 客户端里就报错错误信息大概是 mcp client for codex_apps timed out after 30 seconds. add or adjust star…后面还跟着一段让调参数的提示。这个问题的本质是客户端对单次 tool call 设置了硬超时而我们的服务端又是一个同步执行模型工具不返回客户端就一直等超时后直接判定失败。一开始我还以为是网络问题排查了半天才意识到是客户端侧的行为约束。解决方案不是简单调大超时时间而是把长任务改成异步模式服务端收到请求后立刻返回一个 task_id然后另起线程或者走消息队列执行真实任务工具结果通过 notification 或者客户端轮询的方式再拿。MCP 协议本身对这种异步模式支持一般所以我用了折中方案工具首次调用返回任务已提交的状态同时提供另一个 get_task_result 工具让客户端拉结果。这样既有状态语义又不会卡在单次调用的超时上。这个经历给我一个很强的教训不要默认所有 MCP 客户端行为一致。同一个 server有的客户端会主动重试有的客户端超时后直接中断会话有的客户端会限制工具返回体大小。方案澄清阶段拉的兼容性矩阵联调时真的全用上了。4.2 工具返回过大撑爆上下文第二个高频坑是返回内容大小。MCP 工具的结果是要回到对话上下文里去的模型需要把它和之前的对话历史放在一起综合理解。所以一个工具返回 50KB 的 JSON相当于直接吃掉了几千个 token。如果 Agent 在一个流程里连续调用十几个工具每个工具都返回大段原始数据上下文很快会到上限后面的调用就开始出错要么是模型忘了前面的结果要么是客户端开始截断历史信息。我们的处理方式是在服务端做结果降维。拿浏览器抓取这个场景举例Playwright MCP 可以直接返回页面元素树但元素树动辄上百个节点对模型来说信息密度太低。我们的做法是把它拆成两个工具一个叫 find_element返回的是元素定位信息和关键属性比如 xpath、id、text 摘要另一个叫 extract_page_data专门拉结构化数据返回前先做字段裁剪只保留业务需要的部分。这样 Agent 的每次调用拿到的都是够用但不冗余的信息。还有一类场景必须返回原始数据比如跨系统报表这种我们会限制行数上限默认只返回前 20 行并在结果里附一个 has_more 标记。4.3 跨系统数据不一致从设计稿到代码落地的坐标差异跨栈接入真正磨人的地方在于不同系统的数据语义对不上。我们这次有一条完整链路需要用 MCP 打通从蓝湖/Figma 拿设计稿坐标和标注再让 Playwright/Chrome DevTools 在浏览器里定位元素最后把定位结果反馈给代码生成模块。结果第一轮联调就发现设计稿里的坐标体系和浏览器渲染出来的坐标体系根本不是一回事。设计稿用的是 375x812 之类的固定设计尺寸浏览器里可能经过了 rem 缩放、设备像素比换算、滚动偏移直接拿设计稿坐标去浏览器里找元素找出来全是偏的。这个坑不是 MCP 的问题但 MCP 把不同系统拉到同一条调用链之后这个问题就从没人管的边缘地带变成了阻断主流程的卡点。解决方案是在 MCP server 里加一个坐标转换工具输入设计稿坐标和当前页面的视口信息输出换算后的浏览器坐标和推荐定位策略。这个工具本身也会调用 Chrome DevTools MCP 拿视口数据相当于 MCP server 之间再互相调用。这种server 调 server的模式在跨栈场景里非常常见但要在方案阶段就预留好 token 和鉴权传递的接口否则后面接一个就得重新设计一次。5. 端到端验证我这样设计链路和巡检脚本5.1 测试分层协议层、工具层、业务层端到端验证不是拿一个真实业务跑通就算完那样只能证明刚好这条路径通了证明不了换一个输入、换一个环境也能通。我习惯把验证分成三层协议层、工具层、业务层。协议层验证的是 MCP 握手、工具列表拉取、工具调用格式这些基础能力不需要真实业务数据用 mock server 就能覆盖。工具层验证的是单个工具在不同输入下的表现包括正常参数、缺参、类型错误、边界值。业务层验证才是真正从用户视角走完整条链路Agent 拿到一个任务自动选择工具、传入参数、处理返回结果、继续下一步直到输出最终产物。跨栈项目最容易放松的是协议层因为官方 SDK 保证了协议栈本身就是通的但真实项目中协议通和你的配置对之间隔着很多坑。比如 SSE 的鉴权 header 到底放在哪不同客户端写法不一样协议层测试不覆盖可能根本发现不了。5.2 一套可复制的端到端用例我设计验证用例的时候会特意在用例描述里写清楚预期 Agent 行为和预期工具返回而不只是写调用成功。举个例子针对从设计稿获取首页标题样式这个用例预期 Agent 行为是先调用蓝湖 MCP 获取画板 ID再调用 get_frame_info 拿样式数据最后输出包含字号、字重、颜色 hex 的三条摘要。预期工具返回是明确标注每个字段的来源并给出 JSON 示例。这种描述方式的好处是验证失败时能快速定位到是 Agent 选错工具还是工具返回格式不对还是模型理解偏差。完整链路我还加了一条异常恢复用例。我先人为让某个下游服务返回 500再看 Agent 怎么处理。正常情况下 Agent 应该捕获错误、重试一次、失败后换备用工具或者直接如实告知用户而不是凭空编一个结果。这个测试非常重要因为跨栈系统里下游故障是常态Agent 的容错策略直接决定用户体验。我们从测试结果里发现模型在拿不到设计稿数据时会倾向于猜一个合理的样式值继续往下走这在设计稿场景看着还行但放到生产变更场景就是事故。所以我们在系统提示词里加了一行硬约束任何工具调用失败必须向用户报告原始错误信息禁止补全或猜测。5.3 端到端验证的自动化和上线后观察指标端到端验证我最后做成了脚本化。用一个本地 mock 客户端按预设脚本调用 MCP server 的各个工具模拟 Agent 的行为序列跑完之后对比返回结果和基线。这么做有个附带好处每次服务端有改动我都能在十分钟内跑完一轮完整回归不用每次手动起一个 Agent 慢慢试。脚本里还会记录每次调用的耗时和返回体大小做性能回归参考。上线后第一天我重点看三个指标工具调用成功率、平均耗时、上下文 token 消耗趋势。工具调用成功率反映的是下游依赖是否稳定平均耗时反映的是 MCP server 和外部 API 的整体性能token 消耗趋势则能看出工具返回体是否膨胀如果某天开始某个工具返回值突然变大说明上游数据结构变了需要及时调整裁剪逻辑。这三个指标都不需要额外开发复杂的监控系统有基础日志就能算但对判断这条链路是不是真的能持续稳定跑下去非常有效。最后说一个我自己挺深的体会。MCP 接入这事技术上真正难的从来不是把协议调通而是方案前期愿意花多少时间把边界、语义、环境差异这些听起来很虚的东西定清楚。代码层面的坑大多能靠调试和搜索解决但边界不清晰的坑往往是在上线之后以最难看的姿态跳出来的。把方案澄清当成独立阶段来做而不是走流程的开场白是我这次最想保留的经验。
