很多人在给 AI 接外部能力时卡在同一个问题上：手里已经有一份 OpenAPI 描述文件，到底还要不要额外搭 MCP 服务？反过来，先做了 MCP server，又想知道什么场景其实用 OpenAPI 就够了。这篇不堆概念，只从「描述的是什么」和「怎么被调用」两个角度拆开讲，最后给一份选型和改造的排查顺序。
很多人在给 AI 接外部能力时卡在同一个问题上：手里已经有一份 OpenAPI 描述文件，到底还要不要额外搭 MCP 服务？反过来，先做了 MCP server，又想知道什么场景其实用 OpenAPI 就够了。这篇不堆概念，只从「描述的是什么」和「怎么被调用」两个角度拆开讲，最后给一份选型和改造的排查顺序。
先说一句结论方便记：这两者不是新旧替代关系，而是站在不同位置的两种描述。拿它们比版本号、比谁更先进，基本都会聊偏。真正要判断的只有两件事——你的调用方是谁，以及你愿意把适配成本放在哪一侧。
先分清两者各自在描述什么
OpenAPI 描述的是一个 HTTP 服务本身：有哪些路径、用什么方法、参数怎么传、状态码和返回结构长什么样。读它的主要角色是人、代码生成器和网关。它不关心调用方是模型还是脚本，只保证接口契约清楚。
MCP 描述的是「可供模型调用的能力」：这个工具叫什么、用途用一句话怎么讲、入参 schema 是什么。读它的是模型本身。所以一个在描述接口，一个在描述能力，层级不同，处理的对象也完全不同。
- 如果调用方永远是人写的代码，OpenAPI 一层就足够，不必再加东西；
- 如果调用方是模型，且工具数量会持续增长，就要考虑补一层能力描述；
- 接口数量很少、调用逻辑写死在代码里，加能力描述这层的收益接近零；
- 同一套后端可以同时对外给 OpenAPI、对内给模型提供 MCP 能力，两者并行不矛盾
集成方式差在哪：谁去发起、谁去适配
OpenAPI 路线里，集成方自己写胶水代码，把接口包装成函数再交给模型，鉴权、重试、错误映射全在自己手里。好处是可控，坏处是每加一个接口都要改一次调用侧代码，接口一多就散。MCP 路线里，能力由 server 暴露，客户端按统一方式发现和调用，接入新工具时改动集中在一处，但代价是多了一个进程或连接要维护。
| 对比维度 | OpenAPI 路线 | MCP 路线 |
|---|---|---|
| 描述对象 | HTTP 接口契约 | 模型可调用的能力 |
| 主要读者 | 人、代码生成器、网关 | 模型自身 |
| 适配工作放在哪 | 调用方写胶水代码 | 服务方暴露能力，客户端统一发现 |
| 新增工具的改动点 | 每处调用代码都要动 | 多数集中在 server 侧 |
| 额外维护成本 | 几乎为零 | 多一个进程或连接要盯 |
| 适合的规模 | 接口少、调用方固定 | 工具多、调用方多变 |
什么情况下不适用：一次性脚本、内部低频调用、接口数量个位数时，直接写函数调用往往比搭 server 更省事。反过来，如果你已经在为「每接一个接口就要改一遍客户端」发愁，那说明适配成本已经开始压过维护成本了。
一份对照表：把 OpenAPI 的要素映射到 MCP 工具
- operationId / summary
- 对应工具名与用途描述，用途要写成给模型看的一句话，不是给人看的接口备注
- requestBody 与 query 参数
- 合并成工具的入参 schema，必填项和枚举必须标清楚，否则模型容易编参数
- 返回体
- 不要整包丢回，先裁剪成模型能读的字段，大对象直接返回容易把上下文吃满
- 鉴权信息
- 不放进工具 schema，放在 server 侧的配置或环境变量里，避免随调用参数外泄
- 错误码
- 映射成模型能理解的失败原因，不要把原始堆栈直接抛给模型
这里最容易踩的坑是用途描述写得像接口文档注释。模型看不懂「查询订单列表 v2」这种话，它需要的是「根据用户提供的订单号查询该订单当前状态，订单号必填」。描述写得好不好，直接决定模型会不会乱传参数。
从现有 OpenAPI 迁移或并行维护的排查顺序
- 先分组按调用频次和失败代价给接口分组，高频且易错的先做工具化，长尾的先不加，验证收益再扩
- 跑参数边界逐个接口确认模型能生成的取值都落在合法范围，必要时在描述里补约束，别指望模型自己猜
- 加调用日志记录工具名、参数摘要、耗时和错误类型，回看时才能分清是描述问题还是接口问题
- 分开统计失败上线后按周看一次失败分布，把「描述不清导致的参数错」和「接口本身的错」分开计数、分开修
- 按需回滚如果某类接口工具化后失败率反而更高，先退回代码调用，别硬撑
如果这套流程里你想先看看同类工具实际跑起来什么样，可以到 /tools 翻一下工具目录，对照自己链路的形态再决定要不要动。
几种不该硬上 MCP 的情况
- 接口本身有强事务或长流程，需要多步人工确认的，套一层工具反而更难控；
- 团队里没人能维护常驻进程，连接断了没人处理，不如先留在代码里调用；
- 只做内网批处理、没有模型参与决策的链路，加上能力描述这层没有收益；
- 如果只是想统一鉴权和限流，用网关加 OpenAPI 描述就能解决，不必引入新协议
还有一种情况：你已经有一份维护得不错的 OpenAPI 文件，接口数量也不多，这时候急着搭 MCP 通常只是因为「别家在做」。先算一下适配成本到底落在谁身上，再动手也不迟。
选型不看协议新旧，只看调用方是谁、适配成本落在哪一侧。下一步把你这边的调用方和接口数量对一遍，再去看同类中转站和工具的实际接入形态，判断会更稳，站内导航页有现成分类可以对照。→
常见问题
已经有 OpenAPI 文件了，还需要再做 MCP 吗？
看调用方是谁。如果只是你自己的代码按文档去调，OpenAPI 足够；一旦要让模型自主决定调哪个接口、传什么参数，就需要一份模型能读的能力描述，这时才值得做 MCP。可以先挑两三个高频接口试，跑顺了再扩。
MCP 会不会取代 OpenAPI？
不会，两者管的事情不一样。OpenAPI 描述服务对外长什么样，MCP 描述模型能用哪些能力，底层请求照样可能走 HTTP。现实里常见的是 MCP server 内部再去调那些已有接口，是叠加而不是替换关系。
把接口转成 MCP 工具，最容易踩的坑是什么？
工具描述写得太像接口文档。模型读不懂「按业务规则处理」这种话，只会照着字段名瞎猜参数。描述要说清这个工具干什么、什么情况用、参数取值范围，返回也最好裁剪过，别把整包响应塞回上下文。
