把现有 REST API 包装成 MCP Server：OpenAPI 自动转换的取舍与做法

Q: MCP 会取代 REST 吗？

不会。REST 继续服务浏览器、移动端和传统系统，MCP 只是叠在它之上的一层面向智能体的适配层，让模型能理解并调用这些接口。原有接口一行都不用改。

云上的幻象2026-10-076 分钟阅读2,141 字20

100%

把现有 REST API 包装成 MCP Server：OpenAPI 自动转换的取舍与做法

结论先说：把 OpenAPI 规范自动转成 MCP Server 能省掉八成样板代码，但有两件事必须人工改——工具描述和工具粒度。直接把一个几十端点的规范全量暴露成工具，是让智能体调用成功率下降最快的方式。

映射关系其实很直接

转换本身是机械的：规范里的 operationId 变成工具名，summary 与 description 变成工具描述，requestBody 与 parameters 的 schema 变成工具的 inputSchema。正因为映射规则如此固定，社区里才有那么多一键转换的代理工具，几分钟就能跑出一个能连的服务端。

自动转换后必须人工改的三处

一、描述：给人看的和给模型看的不是一回事

OpenAPI 里的 summary 是写给翻文档的人看的，通常只有半句话。 MCP 的工具描述要回答的是另外四个问题：什么时候该调、什么时候不该调、必须拿到哪些标识、返回大致长什么样。原样继承描述，模型就会在参数不全时乱猜。

比较省事的做法是在规范里加一个自定义扩展字段，专门写面向智能体的说明，转换时优先读取它，这样不用维护两份文档。

二、粒度：按用户意图聚合，不要按端点铺开

# 推荐：按意图命名，模型一看就知道什么时候用
search_products(keyword, category)   # 搜商品
get_product(product_id)              # 取详情
add_to_cart(product_id, quantity)    # 加购物车

# 不推荐：直接映射 CRUD，模型无法判断该调哪个
POST_products / GET_products_id / PATCH_products_id

经验值是单服务端暴露的工具控制在二十个以内。端点更多时，用路径白名单只放出智能体真正需要的那几个，而不是全量注册。

三、鉴权：不要复用超管凭据

代理式方案通常用环境变量注入密钥，默认以 Bearer 方式放进请求头，也支持按服务商要求改成自定义头或从请求体里剥离令牌。原则是给 MCP Server 一个最小权限的专用令牌，并在服务端记录每次调用的 agent 标识、工具名与参数。

两条实现路线怎么选

路线	做法	适合场景
代理式	指向规范地址，配置白名单与密钥，自动注册工具	想快速验证、接口稳定且数量可控
手写包装	按意图挑端点，手工写工具名、描述与参数校验	要上线给真实用户、涉及写操作

代理式的典型配置大致如下，关键是白名单与只读约束：

{
  "mcpServers": {
    "my-api": {
      "command": "uvx",
      "args": ["mcp-openapi-proxy"],
      "env": {
        "OPENAPI_SPEC_URL": "https://api.example.com/openapi.json",
        "TOOL_WHITELIST": "/products,/products/{id}",
        "API_AUTH_BEARER": "${API_READONLY_TOKEN}"
      }
    }
  }
}

跑起来之后用官方调试工具连一次，确认工具列表、参数与返回都符合预期，再接入客户端。调试与联调的完整流程见MCP 错误处理与排查。

最容易翻车的是写操作。删除、下单、发邮件这类不可逆动作，要么干脆不暴露，要么在服务端强制二次确认并留审计日志。智能体在循环里误触发一次写操作，排查成本远高于只读接口。