巨量引擎 MCP 接入说明

01 接入方式与近期变更

本文针对巨量营销 AD 业务工具 MCP，供 DF AI 接入广告账户及报表查询使用；巨量千川等其他产品应使用各自官方配置。

配置项	用途与获取方式
MCP URL	从官方 AD 业务工具文档复制服务地址
API Key（推荐）	在商业开放平台 API Key 管理页面手动创建，配置到 Access-Token 请求头
Access Token（另一种方式）	已注册开发者并完成用户授权时，可使用 API 接口的 Access Token，配置到同一请求头

API Key 与 Access Token 是两种可选凭据。选择一种配置即可；不照搬腾讯广告 MCP KEY + access_token 的双请求头方式。

2026 年 10 月 13 日变更

官方公告预告：历史授权生成的 API Key 将失效，需要替换为手动创建的 API Key。旧“官方应用授权”方式在接入文档中已标记暂停新增。
巨量营销投放场景中关联 POST 接口的写类型 MCP 工具将下线，GET 查询工具保留。写操作若仍需要，改接对应 API；API 本身不因这次公告下线。

文档核对日期为 2026-10-10；上线前再次确认变更已生效范围及工具列表。

来源：AD 业务工具配置说明、官方变更公告。

02 获取 MCP 服务 URL

打开官方“AD业务工具”文档，查看“方式二：开发者授权/API Key生成”的配置示例，复制 URL：

https://open.oceanengine.com/ad/mcp

传输方式选择 Streamable HTTP。上面的地址是服务端点；开放平台文档网页和 API Key 管理页不能填作服务地址。

旧示例将 API_KEY 放在 URL 查询参数中；新建 API Key 仅支持 Header 配置，本方案采用不含凭据的 URL。

来源：官方 AD MCP 配置说明。

03 获取 API Key（建议优先采用）

登录巨量引擎商业开放平台。
进入 工具与支持 → 开发者工具 → API Key管理，也可直接打开 API Key 管理页面。
按页面流程手动创建 API Key，确认该凭据对应的账户与权限；具体字段和可选范围以登录后页面为准。
将获取的凭据填入请求头 Access-Token: <你的API_KEY>，不添加 Bearer 前缀。

本次核验未登录创建凭据；公开页面提示需要登录，未登录时显示“暂无API Key管理权限”。如果登录后仍无管理权限，请向平台支持确认开通条件。

KEY 不写入 URL，不展示在帮助文档或对话中；由后端安全保管，失效后更换并重新测试。

来源：API Key 管理入口、Header 配置要求、手动创建 API Key 迁移说明。

04 使用开发者授权的 Access Token

如果公司已有巨量引擎 Marketing API 对接，且已注册开发者、申请过用户授权，可使用该 API 服务的 Access Token 连接 MCP。先确认授权账户、权限及有效期适用于本次查询。

开发者应用 → 用户账户授权 → 回调接收授权码 → 后端换取 Access Token → 后端按官方机制刷新

通过商业开放平台开发者后台配置应用及回调地址，申请所需能力。
参考文档中心的 Oauth2.0授权 → 如何申请授权&生成授权链接，让有权限的账户用户完成授权。
后端按“获取Access Token”文档换取令牌并保存账户授权关系。
按“刷新Refresh Token”文档管理令牌续期；有效期以实际返回为准。
将有效令牌填入 Access-Token 请求头。

以上是开发者授权流程概要，接口参数与期限应按该产品的官方 OAuth 文档实现，不沿用腾讯广告的参数。手动 API Key 方案不要求在 MCP Header 中再额外附加 Access Token。

来源：AD 业务工具开发者授权说明；OAuth 文档可从官方文档中心选择巨量营销后查阅。

05 DF AI 配置示例

方案 A：使用手动创建的 API Key

{
  "mcpServers": {
    "巨量引擎广告数据查询": {
      "transportType": "streamable-http",
      "url": "https://open.oceanengine.com/ad/mcp",
      "headers": {
        "Access-Token": "<你的API_KEY>",
        "Content-Type": "application/json"
      }
    }
  }
}

方案 B：使用已有开发者 Access Token

URL 和传输方式相同，将 Header 的 Access-Token 值替换为有效的用户授权令牌。两种方案择一，不拼接两个值。官方示例中的 {Access-Token}/{API_KEY} 表示两种可选凭据。

按需限制工具范围

官方支持使用 Tool-Range 请求头指定工具列表，值为 JSON 数组的字符串。例如查询报表及指标定义：

"Tool-Range": "[\"report_custom_config_get_v3\",\"report_custom_get_v3\"]"

工具名称来自当前官方 MCP 页面；接入前通过 tools/list 确认是否可用。工具范围限制不能替代业务账户权限校验。

来源：配置示例及 Tool-Range 说明、巨量广告 MCP 工具页面。

06 DF AI 开发与验证建议

优先验证查询能力：先获取可访问账户，再查询一个授权账户的消耗、点击、转化等报表；暂不依赖即将下线的投放写入 MCP 工具。
分别验证连接与权限：执行 MCP 初始化、tools/list，再调用账户或报表工具；能连接不代表有权读取所有账户。
校验用户与项目：后端将 DF AI 用户及项目权限映射到允许使用的 advertiser_id，调用前校验，避免共用凭据导致越权。
区分凭据生命周期：API Key 的失效处理按后台规则执行；Access Token 由后端按 OAuth 机制刷新，失败时引导重新授权。
处理迁移：10月13日前替换旧授权生成的 Key；仍需要的写操作独立接入对应 Marketing API，并验证授权、幂等及错误处理。

以上为原型评审与开发接入方案。本次未创建真实 API Key，未使用真实广告账户执行调用，也未宣称 DF AI 已完成后端接入。