645个API接入后，MCP服务器踩了7个没人说的坑

当你教AI调用一个API时，一切都很美好。当你要让它在645个API之间自主选择、认证、容错，且凌晨3点无人值守时，教程里的"hello-world"代码会瞬间崩盘。

Rhumb团队刚走完这条路。他们建了一个MCP（模型上下文协议）服务器，代理数百个真实API供AI智能体调用。以下是血淋淋的现场还原——为什么官方教程从不提这些，以及如果你要做超越Demo的产品，必须提前知道的真相。

坑1：API没有稳定的"身份证"

Brave搜索API在文档A页面叫brave-search-api，在文档B页面叫brave-search。当智能体说"用Brave搜索"时，你的服务器得知道这是同一个东西。

这不是Brave的特例。Rhumb团队在支付服务商那里撞墙：同一家公司，多个API版本名字完全不同；通讯平台更乱——SMS、messaging、voice，同一提供商，三个"API"；分析工具则是legacy vs v2的命名混战。

解决方案不是查表，而是把"身份"当成一等公民对待的canonical slug系统，带别名解析。

教程为什么跳过这步？它们只演示一个API。一个API哪来的命名冲突。

坑2：认证方式有5种，且API不会告诉你它要哪种

教程说："把API key加到header里。"这大概覆盖40%的真实API。

Rhumb实际遇到的战场：

Header位置：Authorization、X-API-Key、X-Auth-Token，甚至自定义字段

传输方式：Bearer token、Basic auth、query参数、body字段、甚至cookie

密钥格式：纯字符串、base64编码、带前缀、带签名

问题不是支持全部五种模式。是你的MCP服务器必须在智能体第一次调用前，就知道每个API用哪种模式。如果智能体把Bearer token发给一个要X-API-Key的API，返回的401对智能体毫无信息量。

更阴毒的是：有些API会静默接受错误的认证方式，然后返回空结果而非报错。智能体以为成功了，其实拿到了垃圾。

坑3：智能体生成JSON，API要multipart表单

文档处理API是重灾区。智能体想发送文件解析，构造了一个看起来合理的JSON body，塞了文件内容。API返回400，因为它只接受multipart上传，且字段名必须完全匹配。

"智能体自然产生的"和"API实际接受的"之间的鸿沟，比任何人愿意承认的都要宽：

有些API在JSON里嵌套文件URL；有些要base64编码的文件内容；有些坚持传统的multipart/form-data；还有些要求特定的Content-Type边界字符串。

为什么这对智能体致命？人类开发者会读文档、调整。智能体会把格式错误的请求重试到触达速率限制。

坑4：错误信息是"请稍后再试"，实际问题是密钥格式错误

这是一个生产环境API的真实返回：

{"error": "An error occurred. Please try again later."}

智能体收到这个会真的"稍后再试"。实际问题？API密钥格式无效。重试一万次也没用。

Rhumb遍历645+API后，错误响应的质量差距触目惊心：

顶级选手给结构化错误：类型、错误码、具体参数、人类可读信息。末流选手就一句"出错了"。中间地带充斥着HTTP状态码乱用（500表示认证失败）、错误信息撒谎（"服务不可用"实际是参数缺失）、以及完全空白的响应体。

你的MCP服务器得充当翻译官——把API的胡言乱语，转换成智能体能理解的行动指令。

坑5：速率限制没有标准方言

有些API在响应头里塞X-RateLimit-Remaining，有些用X-Rate-Limit-Remaining，有些干脆不提，直接429。有些在body里告诉你重置时间，有些用Unix时间戳，有些用ISO 8601，有些说"一分钟后"。

智能体不会"等一会儿"。它需要精确的等待策略。你的服务器得把各种方言统一成标准协议。

坑6：文档和实现是平行宇宙

参数名在文档里是user_id，实际只接受userId。必填字段列表和实现不符。枚举值的拼写错误。某些"已弃用"的端点其实是唯一可用的。

Rhumb的解法：自动化测试矩阵，对每个API做真实调用验证，把文档当成不可靠的证人而非真理来源。

坑7：成本模型是黑箱

有些API按调用次数计费，有些按数据量，有些按计算时长，有些按结果复杂度。智能体在规划任务时，需要预判成本——但API不会提前告诉你"这个请求要花0.003美元"。

Rhumb最终为每个API维护了成本元数据，让智能体能在行动前做预算权衡。

如果你正在建MCP服务器，打算接超过一个API，以上哪条坑最让你意外？还是说，你已经踩过了？