你给应用接大模型时，大概会遇到这个岔路：一边是官方文档里的 API key、请求地址、参数 schema；另一边是各种 MCP 服务器、工具清单、配置文件。两者都能让模型干活，但解决的不是同一层问题。这篇按集成方式来拆：先分清调用方向与能力描述方式，再给一套选型对照和落地排查顺序，避免把工具协议当成接口协议来用。
你给应用接大模型时，大概会遇到这个岔路：一边是官方文档里的 API key、请求地址、参数 schema；另一边是各种 MCP 服务器、工具清单、配置文件。两者都能让模型干活，但解决的不是同一层问题。这篇文章只讲一个角度：集成方式上的本质不同，谁调用谁、谁描述能力、谁做鉴权。
先把最容易混的地方点出来：API 是服务方定好的接口约定，你的代码主动发请求；MCP 是把工具或数据源描述成模型可发现的能力清单，由宿主应用去调度。两者不冲突，也不是新旧替代关系。搞混这两件事，常见的后果是把工具协议当成接口协议用，或者反过来拿 API 的排查思路去追 MCP 的配置问题。
先分清谁调用谁：这是两套方向相反的约定
API 是服务方定的接口：你的代码主动发请求、带鉴权、拿结构化响应，主动权在客户端。MCP 是把工具或数据源描述成模型可发现的能力清单，由宿主应用去调度，主动权在调用方的编排层。方向不同，决定了你后面排障时先看哪一侧。
| 对比维度 | API | MCP |
|---|---|---|
| 谁发起调用 | 你的代码主动请求 | 宿主应用按编排调度 |
| 能力怎么描述 | 端点、参数、返回体写死在文档里 | 工具清单、参数描述、调用上下文 |
| 鉴权放在哪 | 请求头带 key，权限由服务方管 | 凭证通常配在宿主应用侧 |
| 关注重点 | 限流、计费口径、错误码 | 能力声明、结果回填格式、上下文长度 |
| 典型入口 | /official-api | /mcp 与 /stacks/agent-apis |
判断口径很简单：如果对方只给了地址和 key，那就是 API；如果给的是一份能力或工具清单加配置项，那就是 MCP 侧的东西。一个模型服务可以只提供 API 而完全没有 MCP 层；一个 MCP 服务器背后也可能只是包了一层某家的 API，这不矛盾。
- 只给地址和 key，没有任何工具描述文件，按 API 处理
- 给的是工具列表加配置项，先按 MCP 侧理解，再确认它底层转调了谁
- 两者都提供时，分别记下各自的凭证来源，别用同一份 key 混着配
- 不确定某家提供哪种接入方式，先到 /official-api 看官方价目与规格页，再去 /mcp 和 /stacks/agent-apis 核对有没有能力清单入口
- 同一家两个入口都出现时，以文档里描述的调用方向为准，不要靠名字猜
鉴权与出错方式不一样，排查顺序也不同
API 的失败大多落在网络、鉴权（key 权限与额度）、参数校验、限流这几类，错误码通常直接告诉你哪一层断了。MCP 的失败更多是配置和数据层面：宿主读不到配置、工具参数描述与模型生成的内容对不上、返回体太长被截断、上下文里塞了过期描述。同一句「调用失败」，两边要查的地方差很远。
- 第一步：确认调用链先搞清楚这次请求是直连 API 还是经宿主调度。看请求日志里有没有中间层的痕迹，有则是 MCP 那条路，没有就按 API 排查。
- 第二步：定位凭证位置凭证是配在你的代码里还是宿主应用的配置文件里。配错位置的典型表现是：本地能跑，换台机器或换个宿主就读不到 key。
- 第三步：判断错误阶段请求发出前出错，多半是配置和工具描述问题；响应解析后出错，多半是返回体格式或长度问题。这两类不要混着改。
- 第四步：量延迟基线想先量出延迟基线，可以用 /tools/speed-test 压一遍，再决定哪些动作值得套一层协议。
还有个实用习惯：把每次失败按「调用链—凭证—错误阶段」三行记下来，攒一段时间就能看出你的项目主要栽在哪一类，而不是每次从零开始猜。
什么情况用 API，什么情况用 MCP
流程固定、步骤已知、要精确控制每次请求的，走 API。比如后台批处理、固定字段抽取、计费敏感的高频调用。动作数量多、需要模型在若干工具里自己挑、参数经常变的，MCP 更省事，等于把「有哪些工具、怎么用」写成模型能读的说明书。
- 核心链路直连 API 保稳定，边缘动作挂 MCP 增加灵活度，两边共用同一套凭证管理和日志
- 强合规内网、需要逐次审计每一次外部请求的项目，多一层调度会放大审计成本，宁可把工具收敛成少量固定 API
- 需要模型自主决定调哪个工具、顺序不固定的探索型任务，用 MCP 描述能力更省维护
- 动作就一两个、参数固定的场景，套 MCP 是给自己加负担，直连 API 更快也更清楚
- 别把两者当成能力上限的差别，它们不决定模型聪不聪明，只决定你怎么接
混合场景最常见。判断标准不是哪个更先进，而是这个动作的调用顺序是代码定死的还是模型要临场决定的。前者用 API，后者才考虑 MCP。
落地清单：从试跑到上线的四个动作
下面这份清单按顺序做，基本能避免把两套东西搅在一起。每步做完都有个能核对的产出，不是空谈原则。
- 第一步：画调用图把每个动作用一行写清「谁发起、要什么凭证、出错谁负责」。图里分不清归属的地方，就是上线后要出问题的地方。
- 第二步：定边界哪些动作必须同一次请求内完成，哪些允许模型分步尝试。只有分步的才考虑上 MCP，能在一次请求里做完的就别拆。
- 第三步：统一凭证与日志不管走哪条路，key 集中管、请求留可检索的日志，出问题时能按时间线还原出「哪一步、哪个凭证、什么错误」。
- 第四步：做降级MCP 那条路挂掉时有没有直连 API 的兜底。没有就补上再上线，别让编排层成为单点。
最后提醒一句：把两条路径的可用性和错误率分开统计，比混在一起看总成功率有用得多。混着算，你永远不知道是模型不行、配置写错还是接口本身在抖。
下一步想对着各家实际接入方式和工具清单入口核一遍，可以到 /mcp 和 /stacks/agent-apis 看当前收录，再回到 /official-api 比对官方规格，判断你的场景该走哪条路。→常见问题
MCP 是不是要取代 API？
不是。MCP 是让模型知道「有哪些能力可用、怎么调」的一层描述与调度约定，底下真正干活的往往还是 API。两者是上下游关系，不是替代关系。什么时候可以不考虑 MCP：动作固定、流程确定的项目，直连 API 更简单也更好排障。
我该先接哪个？
看你的动作数量。只有一两个固定动作就直连 API，省一层调度也省一份排障成本；动作超过五六个并且参数经常变，再考虑用 MCP 把能力清单交给模型自己挑。先跑通一条最小链路，别一开始就把两条都搭起来。
两边都接会不会重复计费或者重复请求？
可能。常见坑是宿主调一次 MCP，MCP 再调一次 API，看起来一次操作实际两次请求。避免办法是把凭证和调用日志统一收在一处，每次操作能对上一条记录。具体某家的计费口径，到 /official-api 对应厂商页面核对当时的规则。
