挂 MCP Server 这事，配通了很爽，配不通能折腾你一下午。我前阵子接了七八个第三方 MCP，总结下来真正坑人的就两块：鉴权和超时。其它的报错都好查，这俩特别容易让你怀疑人生。先把坑摆出来。

坑一：鉴权，header 名和传递方式

第一个 MCP 我挂的是个查物流的 server，文档写着要带 API Key。我照着填了 key，死活返回 401。查了快一个小时才发现，它要的 header 名不是常见的 Authorization，而是自定义的 X-API-Key，文档里那行小字我直接看漏了。

这里给几条血泪经验：

• 先确认 header 的确切名字，是 Authorization: Bearer xxx 还是裸 key，还是自定义 header。差一个字都过不了。

• Bearer 前缀别漏也别多。有的 server 要你自己拼 Bearer，有的它自己加，你再加就成了 Bearer Bearer xxx。

• OAuth 类的最烦。有个 MCP 走的是 OAuth，token 一小时过期。我第一版没做刷新，上线头一小时好好的，过了点全挂。后来在调用前加了个 token 有效期检查，快过期就先刷。

还有个特别隐蔽的：有的平台帮你统一管密钥，你以为填进去就生效了，结果它对某些自定义 header 不透传。这种你得看它的密钥配置是不是支持自定义 header 注入，不支持就只能在请求里手动带。

坑二：超时，默认值往往太短

第二个大坑是超时。有个 MCP 是调一个生成类的接口，正常响应要十几秒。结果我的 Agent 老是报工具调用失败，日志里写着超时。一开始我以为是对方 server 慢，催了半天人家说他们那头正常。

后来才反应过来，是我这边调用 MCP 的超时设的太短，默认才几秒。生成类、要去外部跑任务的接口，十几二十秒太正常了，几秒的默认值根本扛不住。

超时这块要分清是哪一层超的：

1. 客户端调 MCP Server 的超时——这个最常见，调大它。

2. MCP Server 内部调下游接口的超时——这层你改不了，得看对方。

3. 整个 Agent 单步的超时——有的平台对单个工具节点有总时限,这个也得放宽。

我的做法是，凡是涉及外部生成、文件处理、跨网请求的 MCP，超时统一往大了设，宁可等也别误判失败。然后配上重试,但重试要带退避，别失败了立刻猛冲,把对方 server 打挂。

【配图建议：../img/02_mcp.png，MCP Server 接入与鉴权配置界面】

一个让我哭笑不得的细节

说个跑题的。有个 MCP 死活连不上，我把鉴权、超时、URL 全核对了好几遍都没问题。最后发现是那个 server 的域名后面我多敲了个斜杠，/mcp/ 写成了 /mcp//,对方做了严格路径校验直接拒了。就这一个斜杠,搭进去我二十分钟。所以 URL 也别完全信复制粘贴，自己再看一眼末尾。

我现在挂 MCP 的固定动作

踩完这些坑，我形成了套路：先单独把 MCP 用最简单的方式连通(只测一个最简单的工具),确认鉴权和连通没问题,再挂进 Agent。别一上来就在 Agent 里调,出了错你分不清是 MCP 的问题还是 Agent 编排的问题。

平台这块我用的是那种能整合一大批现成 MCP Server、直接勾选挂载的工具,省了不少自己写适配的活,但第三方的鉴权和超时该核对还得核对,平台帮不了你看人家文档。

模型那层我走讯飞 MaaS,直接调现成大模型 API,没自建算力。

总结一句:MCP 接不通,九成是鉴权 header 不对或超时太短,先查这俩,再去怀疑别的。