前阵子给我的小产品补了个很不起眼但影响很深远的接口一个 MCP server。做完以后效果很有意思——原本只能通过网页表单和 REST API 被人调用的报价服务现在能被各种 AI agent 自动发现、自动调用、自动把报价单带回来。放在 2026 年这个节点上这基本相当于给你的产品在 agent 生态里开了一个“系统级入口”。这篇文章不打算复述官方文档就讲我怎么想的、怎么写的、以及一路踩过的坑。适合正在做 AI agent 练手小项目、准备把自家服务接入 agent 生态的独立开发者也适合那些只听过 MCP 但一直没搞明白“这东西到底能给我带来什么”的人。我会把协议原理、工具选型、核心代码、客户端配置、日志管理和并发处理全部串成一整条实操路径你照着走一遍就能复现。1. 为什么给小产品接 MCPAI agent 开始“摸到”你的生意了1.1 先给 MCP 正个名它不是新语言是“接口插座”MCP 的全称是 Model Context Protocol模型上下文协议。2024 年底由 Anthropic 开源随后快速成了 AI 工具接入外部系统的事实标准。你可以把它理解成一个“AI 世界的 USB-C 接口”谁家设备只要支持这个标准插上就能互相通信不需要为每家厂商单独写适配器。整个架构分成三层。MCP host 是宿主程序比如 Claude Desktop、Trae、Cursor 这类 AI 客户端MCP client 是宿主内部负责建立连接的组件MCP server 则是你写的、对外暴露能力的服务端。通信协议基于 JSON-RPC 2.0不是 REST不是 GraphQL是一套专门为“AI 模型调用外部工具”设计的远程过程调用规范。MCP server 内部定义了三种核心原语tools、resources、prompts。Tools 是让 AI 执行的函数Resources 是暴露给 AI 读取的数据Prompts 是预设的提示词模板。大部分实际业务场景你只需要先做好 tools 就能跑通闭环。提示MCP 并不替代 REST API。它是在 AI 客户端和你现有服务之间加了一层“可被发现”的中介。你原有的 API 继续保留MCP server 只是把其中一部分能力用标准化的方式暴露给 agent。1.2 agent 生态已经变了从聊天到“干活”2026 年你再去看市面上的 AI agent 产品盘点会发现一个明显信号能留在牌桌上的没有一个还停留在“陪聊”层面。国内外的 agent 智能体、企业中台、低代码平台连“AI agent 搭建设计”都已经变成常规教程选题。大家讨论的已经从“怎么搭一个 agent”变成了“怎么让 agent 真的下地干活”。那“干活”靠什么靠工具。一个 agent 如果只能基于训练数据回答问题那它永远是个聊天机器人一旦它能调用搜索、数据库、订单系统、报价引擎它才真正变成了一个“数字员工”。像基于 FastAPI LangChain LangGraph 那套方案本质上也是在给 agent 装配外部工具链。这就带来一个残酷的现实如果你的产品不支持 MCPagent 在默认情况下根本“看不见”你。用户让 agent 帮忙找个能生成报价的小工具agent 只会列出它已经联网检索到的服务或者调用那些已经接好 MCP 的竞品。我去年年中给产品补 MCP 接口的动机就是这么简单不想在 agent 消费链里彻底隐形。1.3 我的产品很小但它很适合被 agent “发现”先交代一下背景。我的小产品是面向独立开发者和三五人小团队的报价组件输入需求描述、开发周期、团队人数就能算出合理的报价区间和工期建议。以前只有两套入口一是网页上的交互表单二是给程序员用的 REST API。表单适合人用API 适合会写代码的人用但 AI agent 两者都用不上——它需要的是“能自己发现、自己理解、自己调用”的接口。MCP 的“发现”机制正好解决这个问题。server 启动后agent 会自动读取工具清单每个工具的 description 和参数 Schema 都是自描述的。AI 模型读完清单就知道你这个产品是什么、能干什么、需要哪些参数。它不需要去看你的开发文档也不需要你提前教它怎么拼接 URL。我做完之后做了一个测试在对话里输入“我想做一个带微信登录的小程序大概一个月的开发周期”agent 自动调用了我的报价工具把生成结果直接发回对话。那一刻我就意识到这玩意儿不是锦上添花是必须补上的入口。注意这里的“发现”不是搜索引擎那种爬虫发现而是协议层面的工具自发现。agent 通过 listTools 拿到你的能力清单再根据 user 的诉求决定调用哪一个。你的工具描述写得越清楚agent 调用越准确。2. 动手之前的选型协议原语、传输方式和 SDK2.1 只用 tools 就够了不resources 和 prompts 偶尔也要用我最早以为 MCP server 就是“注册几个函数”后来认真看了协议才发现三个原语各有各的适合场景。我建议初始化项目时不要贪多先把 tools 做好但心里要清楚另外两个原语解决什么问题。ToolsAI 可以执行的函数通常有入参和返回值。适合报价计算、下单、查询状态这类动作。Resources暴露给 AI 的只读数据。适合产品目录、服务条款、价格表这类“AI 需要先读再判断”的内容。我后来就把产品基础信息放成了 resourcesagent 在调用报价工具前可以先读一遍服务范围避免拿完全陌生的需求来问价。Prompts预设提示词模板。适合把“报价前需要收集哪些信息”这类业务规则固化成模板。不过说实话对一个小产品来说prompts 的优先级最低等用户量上来了再补也不迟。如果你上来就把三种原语全铺开维护成本会很快超过收益。最小可用方案就做 tools一条路径跑通再扩展。2.2 stdio 与 SSE两种传输方式的取舍MCP 支持多种传输方式目前最常用的是 stdio 和 HTTPSSE。stdio 模式下MCP server 作为子进程被客户端拉起双方通过标准输入输出通信。本地开发调试、配合 Claude Desktop、Trae、Cursor 这类桌面客户端stdio 是最省事的方案你不用部署服务、不用开端口、不用处理跨域。SSE 模式适合 server 部署在远程服务器、多个客户端通过公网访问的场景。客户端通过 HTTP 建立连接再通过 SSE 接收服务端消息。如果你的产品想要面向“任意 agent 都可发现可调用”这个目标最终一定得支持 SSE 或升级版 Streamable HTTP。大家看那些“Trae IDE 搭载 Burp Suite MCP server 完整指南”之类的教程本质用的也是这套连接逻辑只不过工具换成了安全测试产品。我在本地开发阶段用 stdio联调稳定后补了一个 SSE 入口用于线上。一个 server 代码两种 transport 都支持切换成本非常低。2.3 语言与 SDK为什么我选 Node 而不是 PythonMCP server 官方 SDK 有 TypeScript、Python、Java、Go 等多个版本选择主要看你现有的技术栈。我自己主力栈是 TypeScript所以选了 modelcontextprotocol/sdk。如果你在 FastAPI LangChain LangGraph 那套 Python 生态里用官方的 Python SDK 也一样顺手Java 生态还有 Spring AI 的 MCP 集成做企业服务端很合适。我不用 Python 还有一个具体原因TypeScript 的 JSON Schema 一致性更好。MCP 工具参数用 JSON Schema 描述TypeScript 里我可以把类型定义和校验规则写在一起tsc 编译时就能发现类型漂移。另外 Node 生态的 npx 分发对客户端特别友好用户客户端配置文件里写一行npx -y 包名就能拉起最新版 server不需要预先全局安装。实操建议MCP server 的代码量并不大核心逻辑通常一两百行没必要为了它单独引入一套重型框架。你的业务逻辑还是留在原服务里MCP server 只做一层薄薄的转换层。3. 核心实现怎么让 agent “发现”并“报价”你的产品3.1 先搭一个最小可用的 server 骨架这是 SDK 初始化最基础的代码。我直接用 TypeScript 官方 SDKregisterTool 的第二个参数就是 JSON Schema第三个参数是执行函数。import { McpServer } from modelcontextprotocol/sdk/server/mcp.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; const server new McpServer({ name: my-quote-mcp, version: 1.0.0, }); server.registerTool( discover_product, { keyword: { type: string, description: 搜索关键词比如小程序、网站、API、后台 }, includePricing: { type: boolean, description: 是否返回价格起点默认 true }, }, async ({ keyword, includePricing }) { const result searchCatalog(keyword, includePricing); return { content: [{ type: text, text: JSON.stringify(result, null, 2) }], }; } ); const transport new StdioServerTransport(); await server.connect(transport);贴这个代码是想说明一个点位MCP 工具函数的返回值不是裸数据必须包成content数组数组里每一项是一个带类型的块text 或 image。AI 客户端就是靠解析这个数组把结果呈现给模型的。第一次写时很容易漏掉这层包裹导致 agent 拿到空数据。3.2 “发现”工具的描述有多重要AI 就靠这个理解你工具注册的代码只是骨架真正决定 AI 调用准确率的其实是 description 和参数注释。JSON Schema 的 description 字段是给模型读的写得好不好直接决定 agent 是精准调用还是乱试。我一开始给 discover_product 的 description 写的是“发现产品”结果 agent 经常拿它来问“你们有什么产品”甚至在我需要报价时先调用发现再调用报价多出一步无效交互。后来我把 description 改成了“根据用户描述搜索可提供的产品与服务返回产品编码、名称、计价单位与价格起点。调用报价工具前应先调用本工具确认产品编码”效果立刻提升。AI 模型是依据文本语义来规划工具链的你的描述越接近自然语言任务它的工具编排越合理。参数命名也一样。不要用id、type这种零语义的词要用keyword、includePricing这种模型一眼能看懂的名字。必要的时候把数值单位的约定写进参数注释比如“价格单位为美元”“周期按自然周计算”避免 agent 把用户说的“一个月”直接当成 4 周或把人民币数字当美元。3.3 “报价”工具不要给 agent 设太多枷锁报价工具是这套 MCP server 的核心。我设计了一个 create_quote 工具输入三个参数需求描述、期望周期、团队人数。参数 Schema 长这样{ type: object, properties: { demandDescription: { type: string, description: 用户完整的需求描述包括功能范围、平台、登录方式等 }, durationWeeks: { type: number, description: 期望开发周期自然周可空为空则按默认排期计算 }, teamSize: { type: number, description: 团队人数可空默认 1 } }, required: [demandDescription] }注意我这里只把demandDescription设为必填其余都是可选。一开始我把三个字段全设置成 required结果 agent 在用户描述信息不足时直接报错甚至放弃调用工具转身告诉用户“信息不完整”。AI agent 没有那么强的主动追问能力工具层面的容错设计必须提前做。内部报价计算逻辑我用了一个非常简单的模型基准价乘以需求复杂度系数再乘以周期调整系数。需求复杂度靠一组关键词匹配比如“小程序”加 0.8“AI”加 1.5涉及支付的再额外加权。这个逻辑放在原服务里MCP 工具只负责把参数翻译成内部请求。注意报价结果一定要带上quote_id。这个 id 是后续下单、改报价单、补差价的状态依据。agent 是无状态会话没有 id 的话它一旦断开就彻底找不回这次报价。3.4 日志管理console.log 会毁掉整个 stdio 通道这不是标题党是我踩过的实坑。MCP 的 stdio 传输模式里标准输出 stdout 是协议通道你打一行console.log就等于往协议流里塞了一段噪音。客户端解析 JSON-RPC 包时看到这行脏数据轻则警告重则直接报错表现通常是 server 拉起后过几秒连接就断。正确做法是把日志写到文件或者用 stderr。更讲究一点可以用 MCP 的日志能力向客户端发送结构化日志消息import { createLogger, format, transports } from winston; const logger createLogger({ level: info, format: format.combine(format.timestamp(), format.json()), transports: [ new transports.File({ filename: /var/log/my-quote-mcp.log }), ], });我当时遇到的情况更隐蔽代码里没直接用 console.log但第三方依赖的某条错误处理路径偷偷打了一行。找了两小时才定位。所以我的建议很直接如果你用 stdio 模式在入口文件干脆做一层保护——把console.log整个替换成日志文件的写入。自定义日志管理和协议隔离是你写 MCP server 第一天就要处理的基建问题不要等线上跑起来了再补。4. 让 agent 真的“接上”它客户端配置、本地启动与安全边界4.1 客户端接入一份 config.json 完成最小接线MCP 的一个好处是配置成本极低。以 Claude Desktop 和 Trae 这类兼容客户端为例只需在配置文件里声明 server 启动方式和环境变量{ mcpServers: { my-quote-mcp: { command: npx, args: [-y, my-quote-mcp], env: { PRODUCT_API_KEY: sk-这里填你服务的密钥 } } } }npx -y是这里的关键。它意味着用户不需要预先安装你的包客户端会自动拉取最新版并启动。对独立开发者来说这是分发成本最低的方式。如果你是本地开发调试当然也可以把 command 换成node、args 换成[dist/index.js]这样每次改动不用重新发布 npm 包。env 字段用来透传环境变量。我的 MCP server 里所有业务调用都走原服务的 REST API身份鉴权就靠这个 API keyMCP 工具本身不保存任何敏感信息。4.2 本地启动与联调实操MCP Inspector 是最好用的调试器很多教程停留在“会配置”层面真正联调时会发现一大堆问题。我的完整流程是这样npm run build保证 dist 目录是最新的。用官方提供的 MCP Inspector 启动调试npx modelcontextprotocol/inspector node dist/index.js。浏览器打开 Inspector 面板先看 Tools 列表确认注册的工具名和描述都正确。手动执行一次工具调用检查返回的 content 结构。一切正常后再通过客户端配置走真实链路测试。“本地启动 MCP server 教程”到处都有但真正实用的技巧是先在 Inspector 里跑通一遍再上客户端。因为 Inspector 能看到协议层的原始请求和响应而客户端里 agent 会把你的失败包装成“暂时无法完成”你根本不知道是工具报错还是模型没调用对。4.3 权限与安全给 agent 的权限不能比内部系统还大这个话题我是受那篇“Trae IDE 搭载 Burp Suite MCP server”教程启发的。你看连安全测试这种高风险操作现在都开始让 agent 直接控制工具了说明业界对“agent 操作生产工具”这件事已经有了共识不是不让动是必须控制好边界。我给自己定了三条规则。第一MCP server 只暴露业务白名单工具不开放任意命令执行或文件读取防止 prompt injection 导致的信息泄露。第二所有工具内部都要校验调用来源和身份API key 从 env 传入工具参数永不做信任。第三对工具调用速率做限制同一密钥每秒最多 10 次调用防止 agent 循环失控把原服务打挂。这里说一个容易被忽略的点agent 收到的系统上下文可能被用户输入污染。如果用户诱导 agent 调用工具时带上恶意参数你的工具如果不过滤就会成为攻击入口。所以 MCP server 里每个输入参数都必须按“不可信输入”来处理。5. 并发、超时和那些让人抓狂的坑5.1 AI agent 怎么扛并发先搞清楚你的运行模式很多人一上来就问“AI agent 怎么扛并发”这问题要先分场景。stdio 模式下的 MCP server 是单客户端进程每个客户端拉起一个独立子进程天然隔离、天然分布不存在共享状态竞争。但它的并发能力受限于单进程单连接不适合对外大规模开放。SSE 模式就完全是另一回事了。你的 server 变成一个常驻 HTTP 服务所有客户端都连到同一份代码上这时候必须考虑三件事工具执行不能长时间占用请求线程、关键路径要有超时、计算密集的活要让位给任务队列。我的做法是报价计算如果超过 500ms 就走异步任务先返回“任务已受理请稍后查询状态”这样的结果再提供一个状态查询工具供 agent 轮询。这比硬扛同步等待稳得多。5.2 我遇到过的四个典型错误级别把服务发给十几个人试用之后我整理了一张问题排查表基本覆盖了大部分新手会踩的坑表现可能原因排查方向客户端显示 server 连接失败stdio 通道被日志污染 / Node 版本不兼容检查是否用了 console.log确认 process.stdout 没被第三方占用agent 说“工具出现异常”工具函数抛异常后没格式化返回看 stderr 日志确认代码没有 switch 后走 throwagent 调用了工具但结果为空content 数组格式错误或返回体太大被截断用 MCP Inspector 看原始响应体调用重复导致限流agent 编排时多次重试同一工具工具加幂等键相同参数直接返回缓存结果第四个问题我单独多讲一句。agent 在处理长流程时经常因为上下文超限或网络中断进行工具重试。如果同一报价被重复创建用户会收到两份几乎相同的报价单。我在报价工具里加了一个幂等判断相同 demandDescription 摘要 相同产品编码的请求60 秒内直接返回上次的 quote_id不再新建。5.3 一次真实事故复盘日志救了我一命上线第二个星期有个用户反馈 agent 报价偶发失败。我查了服务端日志发现失败请求都是同一个特征teamSize参数传了字符串2而 JSON Schema 定义的是number。系统做了严格类型校验直接拒绝。看起来是 agent 把用户对话里的“两个人”转成了字符串。这个问题的根源是我的 Schema 设得太严格。修复方案不是让 agent 更聪明而是把工具入参放宽teamSize允许number或字符串数字在工具内部统一做 Number() 转换。从那以后我再也没收到过这类报错。这个经验值得记住MCP server 的校验逻辑要宽容内部转换要严谨。你的服务可以严格要求内部数据但不要对 AI 模型的输出抱有完整富格假设。6. 一些没有写在文档里的经验值MCP server 做完这段时间我个人最深的体会是它不应该成为一个“大项目”它就应该是你原服务的一层薄薄的外接适配器。不要把业务逻辑往 MCP server 里塞塞得越多越难维护。合理状态是MCP server 只做参数转换、身份校验和结果格式化真正的计算、存储、鉴权全部留在原服务。这样你以后换协议、换 SDK、换客户端都只需要调整这薄薄一层。如果你现在正在做 AI agent 练手小项目我建议你挑一个自己已有的小产品或者干脆写一个最简单的报价计算器按这篇文章的路径从零到一跑通一遍 MCP。你会发现当 agent 真的“看到”你的工具并且自动调用成功的那一瞬间你对“AI 原生应用”的理解会完全不同。别再观望了把接口做出来让 agent 先“摸到”你的产品这才是 2026 年不落伍的第一步。