1. 为什么要把 REST API 封装成 MCP 服务1.1 从一个真实场景说起手头有一套跑了三年的订单管理系统REST API 大概四十多个端点Swagger 文档写得还算齐整。上个月团队想把这套接口接进 AI 助手的工具链里让模型能直接查订单、改状态、拉报表。第一反应是写 Function Calling 的 JSON Schema写了十几个之后发现不对劲——每加一个接口就要改一遍工具定义参数校验逻辑还得重写一遍模型调用失败时的错误处理跟 REST 那套 HTTP 状态码完全对不上。这就是把 REST API 封装成 MCP 服务的典型动机。MCPModel Context Protocol本质上是给模型和外部能力之间定了一套标准协议基于 JSON-RPC 2.0 传输把工具Tool资源Resource提示Prompt这三类能力用统一的方式暴露出去。你现有的 REST API 不用重写只需要在中间加一层适配把 HTTP 语义翻译成 MCP 语义。1.2 MCP 到底解决了什么问题不封装行不行行但代价是每个客户端都要单独适配。今天接 A 家的助手明天接 B 家的 IDE 插件后天又要接某个低代码平台每家的工具描述格式都不一样。MCP 的价值在于把能力描述这件事标准化了一次封装任何支持 MCP 的宿主都能直接发现并调用你的工具。从协议层面看MCP 服务端需要实现几个核心方法initialize做能力协商tools/list返回工具清单tools/call执行具体调用如果涉及资源还有resources/list和resources/read。传输层常见两种stdio本地进程间通信和 Streamable HTTP远程调用。本地工具用 stdio 最省事跨网络的服务走 HTTP。1.3 哪些 REST API 适合封装哪些不适合不是所有接口都值得包成 MCP 工具。我的判断标准有三条幂等性优先查询类、状态读取类接口最适合模型反复调用不会出乱子。写操作要谨慎尤其是删除、扣款这类不可逆动作。参数结构清晰如果 REST 接口的参数本身就是扁平的键值对映射到 MCP 的 JSON Schema 几乎零成本。嵌套三层的复杂对象就要多花点心思。单次调用耗时可控MCP 调用通常有超时限制动辄跑几分钟的批处理接口不适合直接暴露得改成异步任务模式。反过来那些依赖会话状态、需要多步交互才能完成的接口比如 OAuth 授权码流程封装起来会很别扭建议先在服务端做一层聚合把多步操作收敛成单个工具。1.4 整体架构怎么摆我采用的方案是薄适配层MCP 服务不碰业务逻辑只做协议转换和参数映射真正的活儿还是交给原来的 REST API。这样做的理由是业务逻辑已经在 REST 层验证过了重复实现只会引入不一致。架构上分三块MCP Server 负责协议处理一个 HTTP Client 负责调后端 REST中间夹一个映射层把 MCP 的 tool 定义翻译成 HTTP 请求。日志和错误处理单独抽出来因为 MCP 的错误返回格式跟 HTTP 差别很大需要专门转换。提示如果你的 REST API 有统一的网关和鉴权MCP 服务可以直接复用网关的 token不要在每个工具里重复实现鉴权逻辑。2. 核心概念对齐REST 与 MCP 的语义映射2.1 Tool、Resource、Prompt 三类能力怎么选MCP 把能力分成三类很多人一上来就把所有接口都塞进 Tool其实不对。Tool是模型主动调用的动作有副作用或者需要参数。比如创建订单查询用户余额。Resource是模型可以读取的数据通常是只读的、有 URI 标识的。比如订单详情页配置文件内容。Resource 的好处是宿主可以把它作为上下文直接注入不需要模型显式调用。Prompt是预定义的提示模板适合把常用的多步操作固化下来。比如生成月度销售报告这个 Prompt 内部可能调了三个 Tool。我的经验是查询单个实体的接口做成 Resource带参数的复杂查询做成 Tool跨多个接口的组合操作做成 Prompt。这样模型用起来最顺手。2.2 参数 Schema 的转换要点REST 的参数通常在 query、path、body 三个位置MCP 的 inputSchema 是一个统一的 JSON Schema 对象。转换时要注意path 参数必须标记为 required因为路径缺了根本拼不出来。query 参数里的数组REST 常见?ids1ids2或?ids1,2两种风格Schema 里统一用type: array实际拼接时按后端要求处理。body 参数如果是嵌套对象Schema 要完整描述别偷懒用type: object糊弄模型看不到字段名就没法正确填参。举个实际的映射例子一个查询订单的 REST 接口GET /api/v1/orders?statuspaidpage1size20对应的 MCP Tool 定义{ name: query_orders, description: 按状态分页查询订单列表, inputSchema: { type: object, properties: { status: { type: string, enum: [pending, paid, shipped, closed], description: 订单状态 }, page: { type: integer, minimum: 1, default: 1 }, size: { type: integer, minimum: 1, maximum: 100, default: 20 } }, required: [status] } }注意description字段的重要性。模型选工具、填参数全靠这段文字写得含糊模型就会乱调。我一般会把什么时候该用这个工具也写进去比如当用户询问某个状态的订单时使用。2.3 返回值格式的取舍REST 返回的 JSON 通常很啰嗦包了一层{code, message, data}。MCP 的tools/call返回的是 content 数组每项可以是 text、image、resource 等类型。我的做法是把 REST 的data部分序列化成 JSON 字符串放进 text contentcode和message用来判断成功失败。如果失败用isError: true标记并把错误信息放进 text。这样模型能明确知道调用是否成功。不要直接把整个 HTTP 响应体原样丢回去模型会被code、timestamp、traceId这些噪音干扰。该裁剪的裁剪该重命名的重命名。2.4 错误语义的对应关系HTTP 状态码和 MCP 错误需要建立映射我整理了一张对照表HTTP 状态含义MCP 处理方式200/201成功正常返回 content400参数错误isErrortrue提示模型修正参数401/403鉴权失败isErrortrue提示检查凭证配置404资源不存在isErrortrue明确告知未找到429限流isErrortrue建议稍后重试500服务端错误isErrortrue返回简要错误不暴露堆栈关键点MCP 的协议层错误比如方法不存在和业务层错误要分开。业务错误通过isError返回协议错误才走 JSON-RPC 的 error 字段。混在一起会让客户端难以区分。3. 动手实现从零搭一个 MCP 适配层3.1 技术选型与项目骨架语言上我选了 TypeScript因为官方 SDK 对 TS 支持最完整类型定义能省掉大量调试时间。Python SDK 也不错如果你的后端是 Python 生态可以优先考虑。项目结构大致这样mcp-rest-bridge/ ├── src/ │ ├── server.ts # MCP 服务入口 │ ├── tools/ # 各工具的映射定义 │ │ ├── orders.ts │ │ └── users.ts │ ├── http-client.ts # 统一的后端调用封装 │ └── config.ts # 后端地址、鉴权配置 ├── package.json └── tsconfig.json依赖就两个核心包modelcontextprotocol/sdk和zod用来定义参数 SchemaSDK 内置支持。HTTP 客户端用原生的 fetch 就够了没必要上 axios。3.2 初始化 MCP Server 与能力声明服务启动时要声明自己支持哪些能力。下面是最小可运行的服务骨架import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { CallToolRequestSchema, ListToolsRequestSchema, } from modelcontextprotocol/sdk/types.js; const server new Server( { name: rest-bridge, version: 1.0.0 }, { capabilities: { tools: {} } } ); server.setRequestHandler(ListToolsRequestSchema, async () ({ tools: [/* 工具清单 */], })); server.setRequestHandler(CallToolRequestSchema, async (request) { // 分发到具体工具 }); const transport new StdioServerTransport(); await server.connect(transport);capabilities里声明了tools客户端就知道可以调tools/list。如果还要暴露 Resource就加上resources: {}。注意stdio 模式下所有日志必须走 stderrstdout 是协议通道往里面 print 任何东西都会破坏 JSON-RPC 消息。这个坑我踩过调试了半天才发现是 console.log 惹的祸。3.3 把 REST 端点映射成 Tool 定义我习惯给每个业务域建一个文件导出一个工具数组。以订单为例import { z } from zod; export const orderTools [ { name: query_orders, description: 按状态分页查询订单。当用户想查看某类订单时使用。, inputSchema: { type: object, properties: { status: { type: string, enum: [pending, paid, shipped] }, page: { type: integer, default: 1 }, size: { type: integer, default: 20 }, }, required: [status], }, // 自定义字段记录这个工具对应的 REST 信息 _rest: { method: GET, path: /api/v1/orders, paramMap: { status: query, page: query, size: query }, }, }, ];_rest是我自己加的元数据SDK 不认这个字段但分发的时候要用。这样工具定义和 REST 映射放在一起改起来不容易漏。3.4 统一的后端调用封装所有工具最终都走同一个 HTTP 客户端好处是鉴权、超时、重试、日志只写一遍export async function callBackend( method: string, path: string, params: Recordstring, any, paramMap: Recordstring, string ) { const url new URL(path, config.baseUrl); const headers: Recordstring, string { Authorization: Bearer ${config.token}, Content-Type: application/json, }; let body: string | undefined; for (const [key, value] of Object.entries(params)) { const loc paramMap[key]; if (loc query) url.searchParams.append(key, String(value)); else if (loc path) url.pathname url.pathname.replace({${key}}, String(value)); else if (loc body) { body JSON.stringify({ ...JSON.parse(body || {}), [key]: value }); } } const controller new AbortController(); const timer setTimeout(() controller.abort(), config.timeoutMs); try { const resp await fetch(url, { method, headers, body, signal: controller.signal }); const data await resp.json(); return { status: resp.status, data }; } finally { clearTimeout(timer); } }超时用AbortController控制默认给 15 秒。后端慢接口可以单独配置更长的超时但别超过 60 秒否则模型那边早就断了。3.5 请求分发与结果转换tools/call的处理逻辑就是查表、调后端、转结果server.setRequestHandler(CallToolRequestSchema, async (request) { const tool allTools.find((t) t.name request.params.name); if (!tool) { return { content: [{ type: text, text: 未知工具: ${request.params.name} }], isError: true }; } const args request.params.arguments || {}; const { status, data } await callBackend( tool._rest.method, tool._rest.path, args, tool._rest.paramMap ); if (status 200 status 300) { return { content: [{ type: text, text: JSON.stringify(data.data ?? data) }], }; } return { content: [{ type: text, text: 调用失败(${status}): ${data.message || 未知错误} }], isError: true, }; });这里有个细节成功时我只返回data.data把外层的code、message剥掉减少噪音。失败时把message带上方便模型理解。3.6 本地调试与联调方法MCP 服务不像普通 HTTP 服务那样能直接用 curl 测。官方提供了一个 Inspector 工具可以图形化地列出工具、填参数、看返回。启动方式npx modelcontextprotocol/inspector node dist/server.js它会打开一个本地页面左边是工具列表右边是调用面板。我一般先用它把每个工具跑通再接到真实的宿主里。如果宿主是 IDE 插件或桌面应用配置里通常要填启动命令和参数。stdio 模式下就是node /path/to/server.js环境变量通过env字段传。调试时把日志级别调到 debug能看到完整的 JSON-RPC 消息往来。4. 工业级封装必须处理的六个硬骨头4.1 鉴权别把 token 硬编码进工具小 demo 里把 token 写死在配置里没问题生产环境绝对不行。我的做法是 MCP 服务启动时从环境变量读凭证或者走一个独立的凭证获取流程。如果后端支持用服务账号的长期凭证比用户 token 更稳。对于需要区分用户的场景可以在initialize阶段通过_meta字段传递用户标识服务端据此选择对应的凭证。不过要注意MCP 协议本身不规定鉴权方式这块得看宿主怎么传。4.2 限流与重试保护后端不被模型打爆模型有个特点它会并发调用工具。一个复杂问题可能同时触发五六个tools/call。如果后端扛不住就得在 MCP 层做限流。我用一个简单的令牌桶控制并发超过阈值就排队。重试只对 5xx 和网络超时做429 要读Retry-After头。重试次数别超过 2 次否则模型那边的等待时间会很难看。const limiter new TokenBucket({ capacity: 10, refillPerSec: 5 }); await limiter.acquire();4.3 参数校验Schema 之外还要做业务校验JSON Schema 只能校验类型和范围业务规则还得自己写。比如结束日期不能早于开始日期订单号必须符合特定格式。这些校验放在 MCP 层做能省掉一次无效的后端调用也能给模型更明确的错误提示。校验失败时错误信息要具体到哪个参数不对、期望什么格式。模型看到参数 startDate 格式应为 YYYY-MM-DD比看到参数错误有用得多。4.4 大结果集的处理分页与截断有些查询接口一次返回几千条记录直接塞给模型会撑爆上下文。我的策略是强制分页默认每页 20 条最大 100 条。如果单条记录字段特别多只返回关键字段其余的在描述里说明完整字段可通过详情接口获取。结果超过一定长度时截断并提示模型结果已截断请缩小查询范围。4.5 日志与可观测性MCP 服务的日志要能回答三个问题模型调了什么工具、传了什么参数、后端返回了什么。我一般记录结构化日志字段包括tool_name、args、duration_ms、status、error。敏感字段手机号、身份证、金额要脱敏后再记。日志输出到 stderr 或者文件别污染 stdout。4.6 版本兼容REST 变了怎么办REST API 升级是常态MCP 工具定义得跟着改。我的做法是给工具名加版本后缀比如query_orders_v2旧版本保留一段时间做过渡。同时在工具描述里标注已废弃请使用 v2。如果后端做了不兼容的字段重命名MCP 层要做兼容映射别让模型感知到变化。这层适配的价值就在这里。5. 常见问题排查速查表5.1 连接与初始化类问题现象可能原因排查方法宿主里看不到工具服务没启动成功手动跑一遍启动命令看 stderr初始化超时stdout 被日志污染检查是否有 console.log工具列表为空capabilities 没声明 tools检查 Server 构造参数调用报方法不存在请求处理器没注册确认 setRequestHandler 已调用5.2 调用与返回类问题现象可能原因排查方法模型填错参数description 写得不清楚补充参数说明和示例返回内容模型看不懂返回了原始 HTTP 响应剥离外层包装只留 data调用频繁超时后端接口太慢加超时控制考虑异步化中文乱码编码没指定确保 Content-Type 带 charsetutf-85.3 我踩过的三个坑第一个坑早期我把所有接口都做成 Tool包括那些只读的配置查询。结果模型每次都要显式调用浪费了一轮对话。后来改成 Resource宿主直接把配置注入上下文省事多了。第二个坑工具描述写得太技术化用了分页查询幂等这种词。模型理解不了经常传错参数。改成查看订单列表可以指定状态和页码之后准确率明显提升。给模型看的文字要用大白话。第三个坑错误处理只返回了 HTTP 状态码没返回具体原因。模型看到 400 就懵了反复重试同样的参数。后来把后端的错误 message 透传出来模型能根据提示自我修正。5.4 性能优化的几个实操点HTTP 连接复用用 keep-alive别每次调用都新建连接。结果缓存对于变化不频繁的查询比如配置、字典加个短 TTL 的缓存。批量合并如果模型连续调多个相似工具考虑在服务端合并成一次后端请求。懒加载工具列表如果特别多可以按业务域分组通过 Resource 动态暴露。6. 从能用到好用几个进阶思路6.1 用 Prompt 固化高频操作有些操作模型每次都要调三四个工具才能完成比如生成月度报告要先查订单、再查退款、最后汇总。这种可以做成 Prompt把步骤和参数模板固化下来。模型只需要填月份剩下的交给 Prompt 内部逻辑。Prompt 的定义比 Tool 复杂一些需要返回 messages 数组。但一旦做好用户体验提升很明显。6.2 给工具加使用示例JSON Schema 里没有示例字段但可以在 description 里写。比如示例查询已支付订单status 传 paid。模型看到具体例子填参准确率会高很多。我一般每个工具至少写一个示例复杂的写两三个覆盖不同的参数组合。6.3 监控模型的实际调用行为上线之后要观察模型怎么用这些工具。哪些工具调用频率高哪些从来没人用哪些经常报错。这些数据能指导你优化工具定义。我一般会记录每次调用的工具名、参数、耗时、结果状态定期分析。发现某个工具错误率特别高就去看看是描述不清楚还是后端有问题。6.4 后续可以扩展的方向如果这套 MCP 服务跑顺了可以考虑几个扩展把多个后端服务的 MCP 聚合到一个网关做统一的鉴权和限流给工具加权限控制不同用户能看到不同的工具集把调用日志接入分析平台做用量统计和成本核算。我个人在实际操作中的体会是MCP 封装这件事难点不在协议本身而在于怎么把 REST 的语义准确地翻译成模型能理解的形式。工具描述写得好不好直接决定了模型用得顺不顺。多花点时间打磨 description 和参数说明比优化代码收益大得多。