企业官网建设流程全解析

最近半年如果你也在做AI开发相关的工具链，大概率绕不开MCP这个词。我这次要复盘的项目，是一次横跨设计稿、浏览器自动化、前端验证、内部数据服务的MCP接入，链路从方案澄清一直延伸到端到端验证。整个排期不算长，但踩的坑比想象中多：协议本身不复杂，真正折腾人的是工具边界、客户端差异、超时策略、上下文尺寸这些细碎问题。这篇文章就是把整个过程整理一遍，适合正在评估MCP、准备把AI能力接进现有工作流的开发者和团队参考。

这个项目最终跑通了一条这样的链路：Agent读取Figma设计稿和蓝湖标注，再通过浏览器自动化工具打开前端页面，截图比对渲染效果，最后调用内部数据服务做接口级校验，整个流程全部通过MCP协议串起来。听起来很顺，实际推进时从方案澄清会开始就反复拉扯。我尽量把决策过程、代码片段、故障排查都按时间线还原出来，保证你在自己项目里能照着走一遍。

1. 项目背景与方案澄清：为什么会在“要不要上MCP”这件事上反复拉扯

1.1 先搞明白MCP到底解决什么问题

MCP的全称是Model Context Protocol，Anthropic在2024年底开源的一个开放协议，目的很直接：统一AI模型与外部工具之间的交互方式。我在项目开始前给团队内部做过一次分享，当时用了一个类比——MCP之于AI工具生态，有点像USB-C之于外设接口。以前接一个工具，要给模型写一堆提示词描述它怎么用，还要自己处理调用格式、错误返回、权限控制；有了MCP之后，工具方把能力暴露成标准化的“工具”，模型的客户端负责发现、调度和传递上下文。

MCP的体系里有三个角色：MCP Host是宿主环境，比如Cursor、Claude Desktop、自研Agent；MCP Server是工具的服务端，负责把能力封装成工具；MCP Client则负责Host与Server之间的协议通信。一个工具封装成MCP Server之后，任何支持MCP的Host都能直接用同一套工具接口，不用再各自适配。这个“一次封装、多处复用”的特性，是我最终坚持在跨组件链路里全面用MCP而非零散REST API的核心原因。

但这也意味着MCP不是银弹。协议只规范了传输层和工具发现机制，不替你做权限管理、不替你决定工具粒度、也不帮你规划返回数据的大小。这些恰恰是实际落地中最容易出现问题的环节。项目刚开始时我们几个人对“要不要全面上MCP”就有分歧，后面澄清会上才慢慢把边界定下来。

1.2 方案澄清会上的三个关键分岔

第一个分岔是技术路线之争：对接现有服务时，究竟是走传统的REST API加SDK，还是把所有能力都包一层MCP Server。我们对比过两条路的差异。REST API成熟稳定，调试工具多，但每次给Agent接入一个新能力，都要写大量提示词解释参数含义、字段格式、错误码；而且每个客户端（比如Cursor、Claude Code）的接入方式都不一样，维护成本被摊到各个端。MCP Server正好反过来，工具定义自带schema，Host能自动发现与填充参数，对Agent非常友好，坏处是生态还在快速演进，碰到兼容性问题时排查链条比较长。

第二个分岔是MCP和RAG的关系。有不少人看到MCP第一个问题是“这跟RAG检索增强生成有什么区别”。一句话解释：RAG管知识，MCP管动作。RAG回答你“Figma设计稿里这个按钮的规范是什么”，MCP执行你“把当前浏览器页面的截图拿出来，跟设计稿做一次像素比对”。两者的目标完全不同，实际链路里经常配合使用，但不要混为一谈。

第三个分岔发生在选型会上：哪些工具用现成的社区Server，哪些必须自己开发。设计稿读取、浏览器操作这类成熟场景，Figma MCP、蓝湖MCP、Playwright MCP都有现成方案；但涉及内部数据和权限控制的环节，必须自研Server，否则第三方Server可能把关键信息暴露给模型，或者把权限放大到不可控的地步。这条边界划定之后，整个项目的架构才真正清晰。

2. 跨栈接入的架构设计与工具选型

2.1 端到端链路设计：从设计稿到页面验证的全流程

跨栈这个词听起来很宽泛，具体到本项目里就是一条清晰的工具链：设计稿读取链路走Figma MCP和蓝湖MCP，前端渲染验证链路走Chrome DevTools MCP，自动化交互走Playwright MCP，数据校验走自研MCP Server。整体流程用文字描述就是这样：

Agent启动任务 → 通过Figma MCP拉取设计稿图层和标注 → 通过蓝湖MCP获取开发规范信息 → 调用Chrome DevTools MCP打开目标页面 → 截图并分析渲染结果 → 通过Playwright MCP执行点击、滚动、输入等交互 → 调用自研MCP Server校验接口返回数据 → 汇总结果并生成修改建议。

设计这条链路时有几个考量。一是尽量复用成熟工具，不在浏览器自动化这类强项领域重复造轮子；二是把每条链路的输出格式统一成文本或结构化数据，避免不同Server返回的格式差异导致Agent“精神分裂”；三是明确权限边界，内部数据校验必须走自研Server，不允许把内部接口暴露给第三方MCP工具。

实测下来，这条链路最大的收益是Agent可以在同一个会话里完成从“看设计稿”到“验证页面实现”的完整闭环，不再需要人在多个工具之间来回搬运信息。但代价是链路里任何一环出问题，整个任务就会卡住，排查成本比传统管道式集成高一个量级。

2.2 热门MCP Server实测对比：Figma、蓝湖、Playwright、Chrome DevTools

项目里实际用到的几款第三方MCP Server，我都按“来源、安装方式、能力边界、实测感受”四个维度做了记录，这里直接列出对比表格。

从这组实测可以提炼一个结论：凡是读取类工具，要注意返回体的大小；凡是操作类工具，要注意超时和状态同步。读取类MCP Server的常态问题是“工具能回答，但回答太长”，一个Figma文件几十个图层如果全部输出，上下文窗口直接爆掉；操作类MCP Server的常态问题则是“操作耗时长，客户端等不及”，后面验证阶段我专门处理这两个问题。

2.3 自研MCP Server的设计：技术栈、通信方式、工具语义

第三方Server解决了通用场景，但内部数据校验、权限管控、自定义动作执行都必须自研。我们最终选择了TypeScript官方SDK，理由有三：团队前端基础好、官方SDK维护活跃、与现有Node.js服务栈一致。

通信方式上，本地开发用了stdio模式，部署到测试环境后切换为streamable HTTP模式。stdio模式适合Claude Desktop、Cursor这种本地Host，模型和Server跑在同一台机器上；HTTP模式则让远端Agent也能跨网络调用。切换的代价是需要处理鉴权、请求超时、并发连接，但这些是现代服务的基本功，相对可控。

工具语义这块是最值得分享的经验。我建议工具命名统一采用“domain.action”格式，比如“design.getLayerInfo”“browser.takeScreenshot”“api.verifyOrder”，这样Agent拿到工具列表时就能快速理解哪个工具服务哪个环节。工具的描述不要偷懒，写清楚参数含义、返回值结构、典型错误，这段描述就是你的API文档，直接决定模型调用工具的准确率。我在项目里吃过描述太短的亏，同一个工具Agent反复猜错参数类型，后来补全描述之后错误率下降了一大截。

3. 从环境配置到联调落地：MCP接入的实操全记录

3.1 环境准备与最小闭环跑通

正式接入前，我先搭了一套最小可跑通环境，避免一上来就被复杂链路卡住。用到的软件版本大致是：Node.js 20+，Claude Desktop最新版，Cursor 0.4x，以及官方示例的Cheese Server。这里强烈建议你按同样的顺序来：先跑通官方例子，再往上叠加自己的逻辑。

Claude Desktop接入MCP的配置很简单，找到配置文件claude_desktop_config.json，把MCP Server的启动命令填进去。

{ "mcpServers": { "cheese": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-everything" ] }, "playwright": { "command": "npx", "args": [ "-y", "@playwright/mcp@latest" ] } } }

配置好重启Claude Desktop，界面里能看到工具列表加载了“cheese”和“playwright”。我当时用“列出工具”这个动作验证了两点：一是协议通信正常，二是工具schema能被正确发现。最小闭环跑通后，再切换到自己写的Server上。

3.2 自研MCP Server的代码骨架与联调过程

自研Server的代码结构不复杂，核心就是定义工具并实现处理函数。我贴一个简化版示例，工具功能是校验订单状态接口。

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { z } from "zod"; const server = new McpServer({ name: "internal-api-mcp", version: "1.0.0" }); server.registerTool( "api.verifyOrder", "校验订单状态，输入订单号，返回订单当前状态和金额信息", { orderId: z.string().describe("订单号，必填，格式为ORD开头加数字") }, async ({ orderId }) => { const result = await fetch(`https://internal.example.com/api/order/${orderId}`, { headers: { "Authorization": "Bearer " + process.env.API_TOKEN } }); const data = await result.json(); return { content: [ { type: "text", text: JSON.stringify(data) } ] }; } ); const transport = new StdioServerTransport(); await server.connect(transport);

这个例子虽然短，但包含了几个关键点。第一，工具的入参用了Zod schema做校验，模型传来的参数如果类型不对，SDK会自动返回错误，不用自己手写参数检查。第二，工具描述写得很直白，模型不需要额外提示就知道该怎么调用。第三，函数内部用到了环境变量里的API Token，实现了鉴权隔离，让模型既能调用接口又拿不到密钥。

本地联调时遇到的第一个问题是服务进程反复退出。排查后发现是stdio模式下标准输出被日志打印污染了——MCP协议用stdout传消息，如果你在代码里“console.log”输出日志，就会把协议数据包打乱。解决办法是把所有日志改写到stderr或专用文件，这个细节让我意识到MCP开发里的“调试手段”和普通Node服务完全不同。

3.3 浏览器自动化联调：让Agent真正“看见”页面

链路里最亮眼的一段是通过Playwright MCP让Agent操作真实浏览器。我在Claude Code里配置了Playwright Server，然后让它打开一个本地前端页面，执行截图和点击。配置和前面Claude Desktop类似，命令行参数指定服务端口和浏览器类型。

{ "mcpServers": { "playwright": { "command": "npx", "args": [ "-y", "@playwright/mcp@latest" ], "env": { "BROWSER": "chromium" } } } }

实操过程很有画面感：Agent先在对话框里说“正在打开订单管理页面”，然后真的启动了一个Chromium实例，加载页面，截了一张图，接着用视觉模型分析截图，发现“页面顶部促销横幅与设计稿不符”，随后调用Playwright的点击操作进入详情页，再调用自研Server验证订单数据，最后生成了一条完整的缺陷描述。

这段联调里印象最深的是要让Agent“看见”页面，就需要不断用工具获取浏览器状态，而每一次截图返回都是一张Base64图片，既耗时又占上下文。后来我加了两个限制：默认只截取指定元素区域，不截整页；截图前尽量先通过DOM查询拿到结构化数据，减少图片依赖。这样一轮操作下来，上下文消耗比以前节省了近一半。

3.4 多客户端兼容：Cursor、Claude Code、Codex的配置差异

项目做到后期，团队里有人用Cursor，有人用Claude Code，还有人在试Codex。同一套MCP Server要配到不同Host里，配置细节差异就别提了。基础Server配置逻辑差不多，但有个关键差异：Claude Desktop和Cursor是“图形界面启动”，从配置文件里加载MCP；Claude Code是“CLI工具”，需要在项目根目录放一个.mcp.json；Codex则有自己的启动参数，还支持运行时动态加载工具。

我踩过的坑是Cursor对stdio服务的启动路径有要求，如果你用“npx -y some-mcp-pack”这种写法，最好指定绝对路径或确保PATH环境正确，否则服务启动失败时界面上没有任何明显报错，只在日志里留一条记录。遇到这种情况，建议先用命令行手动跑一遍Server命令，确认能正常输出，再放回MCP配置里。

多客户端绕不开的还有权限边界：同一个自研Server被三个Host同时连接时，HTTP模式下的连接管理和鉴权必须提前做好，否则一个客户端误操作就可能影响其他会话。我的做法是为每个客户端分配独立的Token，并限制Token可访问的工具范围，最小权限原则在这种场景不是口号，是真能避免事故的。

4. 端到端验证：从功能冒烟到链路稳定性

4.1 验证方案的分层设计

端到端验证不是上线前做一次“全链路冒烟”就完事。我把验证拆成三个层次，逐层推进。

第一层是单工具级验证。每个MCP Server单独测，确认工具能被发现、参数校验正常、返回值格式正确。这一层主要靠脚本化调用，直接构造MCP请求包发过去检查响应。第二层是工作流级验证。让Agent按真实业务场景连续调用多个Server，观察它在工具间切换时是否顺畅，上下文维护是否正常，有没有出现“忘记上一步结果”的情况。第三层是场景级SLA验证。模拟多轮并发任务，统计任务的完成率、平均耗时、超时率，为上线后的监控定基线。

具体验证清单我整理成了一张表，作为团队验收标准：

这套分层方案最大的作用是把“端到端验证”从一句口号变成了可量化指标。上线前我们跑了三天回归，硬是把一个偶发超时问题揪了出来。

4.2 验证过程中踩过的三个真实故障

先说故障一：MCP客户端30秒超时。热词里有人提到“codex_apps timed out after 30 seconds. add or adjust star”，我这边虽然客户端不叫Codex，但机制一模一样。当时自研Server里有个工具会同步执行一个耗时45秒的分析任务，客户端在30秒内没收到响应就直接报超时。排查后发现这类长任务的正确写法是“先返回任务已受理，然后提供查询任务状态的工具”，把耗时计算拆成异步流程。之前没经验，一个同步阻塞就把整条链路打死了。

故障二：上下文被图片撑爆。链路里多个Server都会返回图片，Figma MCP返回设计图缩略图，Playwright返回页面截图。几轮操作下来，一次会话消耗了两百多万token，费用和延迟都控制不住。后来做了改造：Figma能只返回图层名和位置，就不返回图片；Playwright默认只返回裁剪区域截图；必须在对话里用图片时才显式请求。工具返回的内容大小这件事，必须当成一等公民来设计。

故障三：多客户端并发导致共享状态污染。自研Server内存里维护了一个“当前选中订单”的全局变量，结果两个Host同时运行时互相覆盖，A客户端设置的订单号被B客户端冲掉了。排查后用无状态设计替代，把会话上下文交给客户端去传，Server端只做无状态的查询和计算。这也算一个通用经验：MCP Server尽量保持无状态，状态管理放客户端或模型侧。

4.3 上线后的可观测性：怎么盯住MCP链路

端到端验证通过了不代表可以高枕无忧，上线后更需要靠日志和监控盯住链路。MCP的可观测性分三层看：Host客户端日志、MCP Server请求日志、工具内部执行日志。三者要串联起来，关键是统一请求ID。我在自研Server里给每个工具调用都生成了一个traceId，返回到Host日志，这样通过对话ID就能反查整条链路的内部处理过程。

Server端的自定义日志管理也值得一提。MCP Server记录工具调用、参数摘要、返回大小、耗时这几个核心指标，用结构化的JSON格式输出到独立日志文件，便于接入ELK或Loki。我还加了审计日志：谁在什么时间通过哪个Host调用了哪些工具，这既是权限审计需要，也是问题回溯时最重要的线索。

监控指标方面，我重点盯三个：工具调用成功率、P95延迟、上下文消耗量。这三个指标的变化基本能反映链路健康度。成功率低于99%要立即告警，P95延迟异常升高往往意味着某个Server里的外部依赖变慢，上下文消耗量则和费用直接挂钩，需要设置预算告警。

5. 常见问题速查与避坑清单

整理了一份MCP接入过程中的问题速查表，这些内容来自项目里不同成员踩过的真实坑。

有几条避坑经验这里单独强调。第一条：MCP Server的返回内容不是越多越好，模型需要的是“刚好够用”的信息，返回一堆噪声会加大模型判断难度。第二条：不要轻易共享一个Token给所有客户端，按客户端分发最小权限Token，否则一旦某个工具被滥用，责任范围很难收敛。第三条：调试MCP务必用MCP Inspector这类可视化工具，它能直接看到工具列表、schema、入参出参，比盲猜日志高效得多。第四条：协议的版本兼容性要盯紧，MCP还在快速迭代，SDK升级可能带来breaking change，升级前至少跑一遍全部工具用例。

6. 复盘后的一点真实体会

整个项目跑完，我最突出的感受是MCP协议本身并不复杂，真正难点在于“工具语义设计”。给模型暴露什么能力、每个能力拆到什么粒度、描述怎么写、返回什么信息，这些决定模型是否准确可靠，比协议选型本身的影响大几个量级。很多时候模型“不听话”，不是模型质量问题，而是工具设计没到位。

另一个经验，也是我在接下来的项目里会坚持的做法：MCP落地要渐进式。不要一开始就把所有服务都包成MCP Server，先挑一条价值最明确、链路最短的场景跑通，比如“读取设计稿摘要”或“浏览器截图”，验证效果和稳定性后，再逐步扩大工具范围。一上来就十个工具铺开，Agent会在工具选择上混乱，排查问题也无从下手。

最后分享一个后续准备做的扩展：把一些固定流程沉淀成MCP Skill。目前热词里也在讨论MCP Skill，思路是把“工具调用序列”定义成可复用的技能模板，比如“设计稿对比检查”可以一次性串联Figma读取、页面截图、像素比对三个工具，Agent只需要决定“何时用这个Skill”，不用每次自己规划步骤。这会大幅提升任务执行的稳定性和复用性。如果你也正在做类似的跨栈MCP接入，希望这篇复盘能帮你少走几段弯路。