腾讯广告 MCP 接入说明

01 接入需要什么

传输方式为 Streamable HTTP。两个请求头同时配置：Authorization 使用 Bearer + MCP KEY，access_token 单独填写 Marketing API 令牌。

来源：腾讯广告 MCP 简介与鉴权配置。

02 获取 MCP 服务 URL

在官方文档的“基础 MCP 工具”或“快速投放 MCP 工具”中，找到所需能力，复制表格中的“MCP 服务地址”。服务地址是固定的能力入口，无需自行生成。

DF AI 若先做广告 KPI 查询，建议先接 ad-report；后续投放管理按需要新增其他服务。一个地址不覆盖全部工具。

来源：基础 MCP 工具列表、快速投放 MCP 工具。开发者文档网页地址不能当作 MCP 服务地址填写。

03 获取 MCP KEY

1. 登录腾讯营销开发者官网。
2. 进入 管理工具 → MCP 管理 → 获取 MCP KEY。
3. 将获取的 KEY 填写到请求头：Authorization: Bearer <MCP_KEY>。

官网的“腾讯营销 MCP”页面也提供“获取 MCP Key”入口。若账号未显示 MCP 管理或无法获取，请向腾讯营销支持确认账号开通条件。

来源：MCP 鉴权配置、腾讯营销 MCP 首页。

04 获取 Marketing API access_token

access_token 通过广告账户授权获取。需要腾讯广告开发者应用、授权回调地址，以及有相应权限的广告账户管理员。

创建应用 → 管理员授权 → 回调收到授权码 → 后端换取令牌 → 到期前刷新

步骤 1：创建腾讯广告开发者应用

在开发者官网创建应用，在应用程序管理中查看 client_id 与 client_secret，登记回调域名。此处是腾讯广告的应用凭据。

回调地址由你们开发的后端提供，用于接收腾讯返回的授权码。官方要求使用 HTTP 或 HTTPS、不指定端口号，主域名与创建应用时登记的回调域名一致；参数中的地址需 URL 编码。

步骤 2：管理员打开授权页面

https://developers.e.qq.com/oauth/authorize
?client_id=<你的应用ID>
&redirect_uri=<URL编码后的回调地址>
&state=<随机校验值>
&scope=ads_insights

以上分行仅便于阅读，实际使用时拼接为一条 URL。广告报表查询先申请 ads_insights；需要投放管理时再根据功能申请 ads_management 等权限。state 由后端生成并在回调时校验。

步骤 3：接收授权码

管理员登录并确认授权后，腾讯跳转至登记的回调地址，携带 authorization_code 和 state。授权码有效期为 5 分钟，后端收到后及时换取令牌。

步骤 4：后端调用 Token 接口

请求方法：GET；请求地址：https://api.e.qq.com/oauth/token。

成功后读取 data.access_token，并保存返回的 refresh_token、access_token_expires_in、refresh_token_expires_in，以及授权账户与权限信息。有效期以实际接口返回为准。

步骤 5：更新过期令牌

使用同一 Token 接口，传入 client_id、client_secret、grant_type=refresh_token 和 refresh_token，获取新的 access_token。刷新凭据失效后，需要重新授权。

来源：获取 Authorization Code、获取或刷新 Token。

05 广告报表 MCP 配置示例

{
  "mcpServers": {
    "腾讯广告报表查询": {
      "transportType": "streamable-http",
      "url": "https://ai.e.qq.com/mcp-servers/ad-report",
      "headers": {
        "Authorization": "Bearer <你的MCP_KEY>",
        "access_token": "<你的Marketing_API_access_token>"
      }
    }
  }
}

将占位内容替换为实际凭据。此文档不包含真实密钥；实际服务应由后端保管凭据并自动更新令牌。

06 DF AI 开发与验证建议

1. 先确认是否已有授权服务：若公司已有腾讯广告 Marketing API 对接，确认应用权限、授权账户与用途是否适用，再复用已有令牌管理服务。
2. 补齐后端链路：提供授权发起、回调校验、令牌换取与刷新能力，密钥不进入聊天上下文或前端公开配置。
3. 建立权限映射：将 DF AI 登录用户及项目权限映射到允许访问的腾讯广告账户，调用时校验 account_id；MCP KEY 不替代用户权限校验。
4. 分两层验证：先验证 MCP 初始化和工具列表，再查询一个已授权账户的报表。服务连接成功不代表业务账户授权正确。
5. 处理失效：区分 KEY 错误、access_token 过期、账户未授权和权限不足，按原因刷新或引导重新授权。

以上为接入与开发方案，尚未表示 DF AI 已实现真实 OAuth 回调或自动刷新。本文用于原型评审和开发参考。