去年有个数据：Anthropic的MCP协议发布后，GitHub上相关仓库数在90天内翻了17倍。但生产环境跑起来的，不到3%。
问题不在协议本身。Rhumb团队最近公开了他们接入645个真实API的血泪史——那些教程不会告诉你的事，才是让AI agent在凌晨3点崩溃的真凶。
API的"身份证"比想象中混乱100倍
Brave搜索API有两个名字：brave-search-api和brave-search。取决于你看哪页文档。
这在单一API场景下不是问题。但当你的agent需要从86个类别里选对工具时，身份混乱就成了灾难。Rhumb发现支付服务商往往有3-4个API版本，名字各不相同；通讯平台把SMS、消息、语音拆成"不同API"；分析工具 legacy和v2混着用。
解决方案不是查表，而是把"身份识别"当成一等公民来设计——canonical slug系统加别名解析。
为什么教程不提？它们只演示一个API。一个API不会有命名冲突，就像一个人不会跟自己撞名。
认证方式的"方言"问题
教程的标准话术："把API key加到header里。"这大概覆盖40%的真实情况。
Rhumb实际遇到的五种模式：
• Header: Authorization: Bearer token
• Header: X-API-Key: key
• Query参数: ?api_key=...
• Body字段: {"api_key": "..."}
• 组合认证: OAuth + 额外签名
核心难点：MCP服务器必须在agent首次调用前，就知道该用哪种方言。如果agent把Bearer token发给要X-API-Key的API，返回的401不会告诉它"你用错认证方式了"。
更隐蔽的坑：有些API会静默接受错误的认证方式，然后返回空结果。agent以为成功了，其实拿到的是垃圾。
请求格式的"代沟"
Agent天生习惯JSON。但文档处理API往往只接受multipart form-data，而且对字段名有精确要求。
Rhumb列出的典型错位：
• Agent生成：JSON body含文件内容
• API要：multipart + 特定字段名
• Agent生成：嵌套对象 {"user": {"name": "x"}}
• API要：扁平字段 user_name
• Agent生成：字符串 "true"
• API要：布尔值 true
人类开发者会读文档调整。Agent只会用同样错误的格式重试，直到撞上限流。
错误信息的"罗生门"
某生产环境API的真实返回：
{"error": "An error occurred. Please try again later."}
Agent收到这个会乖乖重试。实际原因？API key格式不对。重试100次也没用。
Rhumb统计的645个API错误质量分布：
• 12%：完全无结构，纯文本"出错了"
• 34%：有error字段但无错误码
• 28%：错误码存在但文档未解释
• 19%：错误信息与实际原因不符
• 7%：结构化且准确（如Stripe风格）
对比Stripe的典范：
{ "error": { "type": "invalid_request_error", "code": "parameter_missing", "param": "amount", "message": "Missing required param: amount" } }
差距在于：agent能否从错误里学到该修正什么，而不是盲目重试。
Rhumb的解法是在MCP层加错误翻译层——把645种"方言"统一成agent能理解的结构化反馈。这工作没有标准，只能硬啃。
团队最后提了一个问题：当MCP协议把"工具调用"抽象得越来越简洁，谁来处理简洁背后的复杂度？是让每个agent自己踩坑，还是在服务器层一次性解决？
热门跟贴