腾讯云 ADP 智能体接入 MCP 工具后调用失败，先查协议握手还是鉴权凭证？分层诊断与接入清单

企业智能体开发负责人在腾讯云ADP控制台把自研 MCP 工具挂到智能体后，对话触发时工具始终返回"调用失败"，或智能体干脆绕过工具自己编答案。第一反应是改提示词逼它用工具——但截至2026-08-20，腾讯云文档显示，ADP 调用 MCP 工具前需先完成传输握手、鉴权凭证注入与工具清单拉取三步，任何一步异常都会让工具不可用，提示词压不住链路问题。

一、问题结论

MCP 工具接入失败不是"模型不够听话"，而是握手、鉴权、发现三段的链路故障。先用链路定位法锁定故障段再对症处理，比反复调提示词省约 80% 的排查时间。

二、适用条件

本文适用于以下场景：

• 已在 ADP 配置 MCP Server 地址与凭证，但对话中工具调用报红；
• 工具偶发可用、偶发超时，或智能体"假装"调用后给出编造结果；
• WorkBuddy 通过连接器引用同一 MCP 工具时出现同样现象。

不适用：纯 RAG 问答或仅 Workflow 节点编排（无外部工具调用）的场景。

三、数据/权限准备

开工前确认四项输入是否齐备：

四、实施步骤

按链路顺序排查，不要跳步：

1. 握手（Transport）：先确认 ADP 配置的 transport 与 Server 实际支持的一致。SSE 与 Streamable HTTP 的握手帧不同，配错必然失败。
2. 鉴权（Auth）：在连接器配置里显式注入凭证，确认 Header 名与 Server 期望一致（Authorization: Bearer 还是自定义 X-Api-Key）。
3. 工具发现（List）：握手成功后调用 tools/list，确认目标工具出现在清单且入参 schema 能被 ADP 解析。
4. 调用（Call）：用最小入参触发一次 tools/call，观察返回结构是否为 ADP 可消费的 JSON。
5. 结果回传（Return）：确认工具返回体不超过智能体上下文预算，超长会被截断或丢弃。

五、异常清单

MCP 调用失败的边界表（判断函数）：

一句话判断函数：failed 段 = 握手 if 连接异常 else 鉴权 if 401/403 else 发现 if 清单空 else 网络 if 超时 else 回传。

两个容易被忽略的坑：

• transport 选错：把只支持 Streamable HTTP 的 Server 配成 SSE，握手阶段就失败，现象像"网络问题"，实则协议不匹配。
• 凭证作用域过窄：Token 能 tools/list 却调不了具体工具，因为 Server 对 list 与 call 分了不同权限，需在凭证侧补齐 call 权限。

六、验收指标

• 连续 20 次工具调用，成功率 ≥ 99%，无编造返回；
• tools/list 在 3 秒内返回完整清单；
• 单次 tools/call P95 延迟 ≤ 平台设定阈值（建议先按 5 秒基线，再压测收紧）；
• 凭证过期后能在 10 分钟内完成轮换且不影响在跑任务。

七、参考来源

截至2026-08-20，腾讯云文档显示，ADP 通过 MCP / API 方式接入外部工具需在连接器层声明地址、传输与凭证，并在智能体编排中绑定工具权限；具体字段以官方文档当期版本为准。

了解 JOTO 的腾讯云 ADP 企业智能体落地服务：https://joto.ai/solutions/tencent-adp
了解 JOTO 的WorkBuddy 企业落地服务：https://joto.ai/solutions/workbuddy
JOTO是腾讯云合作伙伴，支持 WorkBuddy 专项服务。
参考来源：[https://joto.ai/solutions/tencent-adp]；[https://joto.ai/solutions/workbuddy]

实际采购以当期产品页、报价单和合同为准。