跳到主要内容

TradPlus MCP 使用说明

修订历史​

发布时间修订说明
2026-07-28更新至 v0.21；SDK 事件明细支持查询已关闭源
2026-07-22支持调整中介组优先级
2026-07-15SDK 事件支持按中介组过滤；报表支持填充时长；补充事件下钻说明
2026-07-06明确 V2 报表不支持中介组过滤；V4 支持默认中介组
2026-07-03对齐 v0.17.0-release：补充报表服务地址说明、漏斗与 SDK 事件工具；更新工具数量
2026-06-17新增用户价值/留存扩展、新增用户分析、设备层级报表等 MCP 工具；补充常用参数与对话示例
2026-05-28首版：接入方式、凭证、工具索引与常用参数、写操作安全、典型提示词

1. 简介​

TradPlus MCP（Model Context Protocol）服务把 开发者后台 OpenAPI 封装成一组 MCP tools，供支持 HTTP/SSE 接入的客户端（如 Cursor）在对话中查询配置、拉报表、做巡检，并在确认后执行少量写操作。

与直接调 HTTP OpenAPI 相比，MCP 的特点：

  • 自然语言驱动：用「查应用列表」「看某广告位配置总览」等描述，由客户端自动选择 tool 与参数。
  • 稳定工具名：每个能力对应固定 tool 名（如 list_apps、list_placements），参数为 JSON 对象，字段见下文各 tool 说明。
  • 凭证由客户端提供：服务端不保存你的 API Key；每次请求通过 Header 传入 X-TradPlus-Bear / X-TradPlus-Secret。
  • 写操作有闸门：写类 tool 必须传 confirm=true；服务端还可通过 MCP_ENABLE_WRITES=false 切为只读。

各 tool 的业务语义以 OpenAPI 约定为准；缺参时由服务返回参数说明表。本文说明 如何接入 MCP、如何调用 tools、常见排错。新增报表类 tool 是否可用，取决于当前 MCP 服务版本；如有疑问请联系客户经理确认。

2. 适用场景​

场景说明
在 IDE 里用自然语言查配置、报表配置 MCP 后由 Agent 自动选 tool
多步巡检（账号范围 → 应用 → 广告位 → 广告源）使用 summarize_*、validate_access_scope 等聚合 tool
经确认后改配置写 tool + confirm=true，写前先用只读 tool 核对资源 ID
Shell 脚本 / CI 批量导出建议直接使用 OpenAPI 或贵司既有自动化；MCP 面向交互式 Agent

3. 获取凭证​

在 TradPlus 开发者后台 「我的账号」→「API Key」 获取：

名称HTTP Header说明
API KeyX-TradPlus-Bear用户身份
密钥X-TradPlus-Secret请求签名

不要把真实 bear、secret 提交到 Git、工单或截图。下文示例一律使用占位符。

4. 服务地址​

用途地址
配置查询（OpenAPI）https://api-developer.tradplusad.com
报表数据服务https://openapi.tradplusad.com
MCP 对话入口https://mcp.tradplusad.com/sse

配置查询与报表查询使用不同服务地址。接入 MCP 后，您只需在客户端填写 API Key，服务端会自动把配置类与报表类请求路由到正确地址，无需手动区分。

若您自行部署 MCP 或使用测试环境，请联系技术支持确认地址配对是否正确。

5. 接入方式​

5.1 HTTP/SSE​

在 Cursor 等客户端中配置 MCP：SSE 端点 + 每次请求 携带凭证 Header（对外仅支持此方式）：

{
  "mcpServers": {
    "tradplus-ssp": {
      "url": "https://mcp.tradplusad.com/sse",
      "headers": {
        "X-TradPlus-Bear": "<your bear>",
        "X-TradPlus-Secret": "<your secret>"
      }
    }
  }
}

配置文件路径（Cursor）：工作区或用户目录下的 .cursor/mcp.json。修改后需在 Cursor 设置中 刷新 MCP 或重启客户端。

若网关要求 Authorization: Basic ... 而非自定义 Header，以运维提供的接入说明为准；MCP 服务解析的是 X-TradPlus-Bear 与 X-TradPlus-Secret。缺任一头会返回明确错误（如 missing TradPlus Bear），便于在 .cursor/mcp.json 的 headers 中排查。

6. 验证 MCP 是否生效​

配置并刷新 MCP 后，在 Agent 对话中尝试：帮我查询所有广告平台列表

正常情况下会调用只读 tool list_adsources。其它可快速验证的提示词：

提示词（示例）预期 tool
查看我的应用列表list_apps
检查当前账号权限概览summarize_current_access
查询 2026-05-01 到 2026-05-07 的 revenue 报表query_v4_report
查询用户价值或留存曲线query_ltv_report / query_user_retention_report
获取设备层级报表下载链接（需提供 date、app_uuid）query_device_report
查看广告漏斗分析（需提供日期与应用）query_funnel_report
查看某应用的配置总览（需提供 app_uuid）summarize_app_configuration

7. 工具索引​

当前约 62 个 MCP tools（以服务端 HandlerMap 注册为准），按类别列出。调用时传入 JSON 对象 作为参数；写操作另需 "confirm": true。

7.1 只读：应用、广告位、场景​

tool说明
list_apps应用列表 / 按 app_uuids 查询
get_app_info根据商店链接补全应用信息（app_url）
list_adseats广告位列表
list_adscenes广告场景列表
list_app_categories应用分类

7.2 只读：广告源、平台、授权​

tool说明
list_placements广告源列表（currency 必填）
get_placement_list_by_app按应用查广告源
list_adsources经典广告平台 ID 列表
new_get_adsource_list按 ad_type、os 过滤的平台目录
list_api_tokens已授权 API Token 列表
get_api_token_list_detailToken 详情
get_account_template平台授权字段模板

7.3 只读：中介组、AB 测试、字典​

tool说明
list_intermediary_groups中介组列表
list_group_placements中介组内广告源项
list_abtestsAB 测试列表
list_regions / list_cities国家地区 / 城市

7.4 只读：报表​

tool说明
query_v2_reportV2 综合报表（兼容）
query_v3_reportV3 综合报表（兼容）
query_v4_report通用 V4 报表
query_v4_api_report三方 API 维度报表
query_v4_tp_reportTradPlus 平台报表
query_ltv_report用户价值 1–90 天（广告网络数据）
query_tpltv_report用户价值 1–90 天（TradPlus 统计）
query_user_retention_report用户留存 2–90 天
query_ltv_imp_report用户 LTV 展示 1–90 天（TradPlus 统计）
query_user_arpu_report新增用户 ARPU 1–90 天
query_user_imp_report新增用户人均展示 1–90 天
query_user_ecpm_report新增用户 eCPM 1–90 天
query_user_type_report新老用户日维度指标
query_deu_retention_reportDEU 留存渗透率
query_funnel_report广告漏斗分析
query_sdk_event_logSDK 事件汇总
query_sdk_event_log_detailSDK 事件明细
query_device_report设备层级报表 CSV 下载链接
query_v4_abtest_reportAB 测试报表
query_v4_app_forecast_report应用预估
query_v4_ab_confidence_reportAB 置信度
query_active_user_report活跃用户

7.5 聚合与权限​

tool说明
validate_access_scope校验对 app_uuid / adseat_uuid 的可见性
summarize_current_access当前账号资源摘要
summarize_app_configuration单应用配置总览
summarize_adseat_overview单广告位总览
summarize_platform_auth_health平台授权健康度
summarize_platform_usage平台使用统计

7.6 Agent 引导​

tool说明
list_workflows推荐多步工作流说明
get_usage_guide使用指南片段
get_faq常见问题
get_tp_cli_downloads查询 CLI 各平台下载地址（无需 API Key）

不确定用哪个 tool 时，可先调用 get_usage_guide 或 summarize_current_access。需要安装命令行工具时，可让 Agent 调用 get_tp_cli_downloads 获取各系统下载链接。

7.7 写操作（需 confirm=true）​

tool风险说明
upsert_adscene低创建/更新广告场景
create_adseat / update_adseat低创建/更新广告位
update_app低更新应用
create_app / delete_app中创建/删除应用
upsert_placement / toggle_placement中创建/更新/启停广告源
update_api_token / save_authorization_info中授权相关
upsert_intermediary_group中中介组
reorder_intermediary_groups中调整同一广告位 / AB 分组下自定义中介组优先级
update_group_placement / toggle_group_placement中中介组内广告源项
create_abtest / modify_abtest高AB 测试配置
start_abtest / close_abtest高启动/关闭 AB（影响流量）

写 tool 标记为 destructive；成功后通常会 回读 对应资源。

8. 常用 tool 参数​

参数均为 JSON 对象 的键。类型为「整数」时传数字，不要传字符串。

8.1 list_apps​

字段类型必传说明
app_uuidsStringN逗号分隔，最多 100；有则忽略分页
pageIntN默认 1
limitIntN每页条数

8.2 list_adseats​

字段类型必传说明
app_uuidStringN*与 adseat_uuids 二选一
adseat_uuidsStringN*逗号分隔
pageIntN默认 1

8.3 list_placements​

字段类型必传说明
currencyStringYUSD 或 CNY；漏传报 1001
adseat_uuidsStringN逗号分隔
app_uuidsStringN逗号分隔
adsource_idsStringN逗号分隔
placement_idsStringN逗号分隔
is_onIntN0 关 / 1 开 / -1 全部
pageIntN默认 1

示例：{"currency":"USD","adseat_uuids":"<adseat_uuid>","is_on":-1}

8.4 validate_access_scope​

字段类型必传说明
app_uuidStringN*与 adseat_uuid 至少传一个
adseat_uuidStringN*与 app_uuid 至少传一个
currencyStringN默认 USD

8.5 summarize_app_configuration​

字段类型必传说明
app_uuidStringY应用 UUID
currencyStringNUSD / CNY，默认 USD

8.6 summarize_adseat_overview​

字段类型必传说明
adseat_uuidStringY广告位 UUID
currencyStringYUSD 或 CNY

8.6a query_v2_report / query_v3_report​

遗留 V2/V3 综合报表。不支持中介组（group_id）过滤；按中介组查报表请使用 query_v4_report（group_id 可传 0 表示默认组）。

8.7 query_v4_report​

字段类型必传说明
start_dateStringYYYYY-MM-DD
end_dateStringYYYYY-MM-DD
metricsStringN如 revenue,impression,click；可含 fillTime（填充时长）
group_byStringN如 date,adsourceId
app_uuidsStringN逗号分隔
adseat_uuidsStringN逗号分隔
group_idIntN中介组过滤；可传 0 表示默认组

说明：fillTime 为综合报表填充时长，不等于中介管理「应用层面」请求/填充导出。按中介组过滤请用 V4，勿依赖 V2 报表的 group 过滤。

8.8 query_ltv_report / query_user_retention_report 等（用户价值与留存）​

常用字段如下；完整 HTTP 参数与返回结构见 数据报表查询 API 文档中对应接口说明。

字段类型必传说明
start_dateStringYYYYY-MM-DD
end_dateStringYYYYY-MM-DD
metricsStringN逗号分隔；默认 all（如 ltv1,ltv7、kp1,kp7、arpu1）
group_byStringN逗号分隔；默认 date,app；用户价值类可含 placementId，留存与 DEU 类不可按广告位聚合
app_uuidsStringN应用 UUID，逗号分隔
areasStringN国家代码，逗号分隔
channelsStringN渠道，逗号分隔
app_versionsStringN应用版本，逗号分隔
placement_idsStringN广告位 UUID，逗号分隔（筛选；留存/DEU 不可写入 group_by）
currencyStringNUSD 或 CNY
timezoneStringNUTC+0 / UTC+8 / UTC-8

query_user_type_report 无 group_by，固定按日与新老用户类型返回。

8.9 query_user_type_report（新老用户）​

字段类型必传说明
start_dateStringYYYYY-MM-DD
end_dateStringYYYYY-MM-DD
app_uuidsStringN应用 UUID，逗号分隔
user_typesStringN1 新用户、2 老用户，逗号分隔
channelsStringN渠道过滤
areasStringN国家代码
currencyStringNUSD 或 CNY

8.10 query_device_report（设备层级报表）​

字段类型必传说明
dateStringY单日 YYYY-MM-DD
app_uuidStringY应用 UUID
api_versionStringNv3 或 v4，默认 v4
timezoneStringNUTC+0 / UTC+8 / UTC-8
currencyStringNUSD 或 CNY

返回 url_cn、url_en、url_in 等下载链接字段（链接有效期有限，请及时下载）。

8.11 query_funnel_report（广告漏斗）​

字段类型必传说明
start_dateStringYYYYY-MM-DD
end_dateStringYYYYY-MM-DD
app_uuidStringN*与 app_name 二选一
app_nameStringN*按应用名称模糊匹配
viewStringNsummary（默认）或 detail
avg_methodStringN汇总方式，如 dau

国家、渠道、广告位类型等筛选字段见数据报表 API 文档。

8.12 query_sdk_event_log / query_sdk_event_log_detail​

SDK 事件汇总与明细。常用必填项为日期范围、应用 UUID、广告位 UUID。

字段类型必传说明
start_date / end_dateStringY明细须为同一天
app_uuidStringY应用 UUID
placement_uuidStringY广告位 UUID
group_idIntN按中介组过滤，口径与 V4 一致
include_closedBoolN仅明细：与 group_id + tradplus_placement_id 联用时包含组内已关闭源，用于查历史事件；默认 false
event_id / metric—明细必填metric=adsource / load_time 仅支持 event 800/801
tradplus_placement_idStringNTradPlus 后台广告源 ID（非三方 networkPlacementId）

event 800 排障优先 error_code；error_msg 往往无有效文案明细。缺参时 tool 返回参数说明表。include_closed 不改变「只传 group_id」时的开启源汇总口径。

8.13 reorder_intermediary_groups​

调整同一广告位、同一 AB 分组内自定义中介组优先级。须 "confirm": true。

字段类型必传说明
adseat_uuidStringY广告位 UUID
bucket_idIntYAB 分组 ID；无 AB 时传 0
group_listString / ArrayY按高→低排序的中介组 ID；须含该 bucket 下全部自定义组；不含默认组 0
currencyStringYUSD 或 CNY
confirmBoolY必须为 true

示例：{"adseat_uuid":"<uuid>","bucket_id":0,"group_list":"11,33,22","currency":"USD","confirm":true}

8.14 new_get_adsource_list​

字段类型必传说明
ad_typeIntY广告位类型：1 原生 / 2 插屏 / 3 开屏 / 4 横幅 / 5 激励
osIntY1 Android / 2 iOS

8.15 写操作通用​

除业务字段外，所有写 tool 必须包含 {"confirm": true}。

upsert_placement 等复杂写操作字段较多（如 adseat_uuid、adsource_id、placement_config、is_auto_create 等）。缺参时 tool 会返回 参数说明表，可按表补全后重试。

9. 参数约定​

  1. 字段名：使用本文各 tool 表格中的键名（如 app_uuid、start_date、currency）。
  2. 数字：ad_type、os、adsource_id、is_on 等传 数字，勿传 "4" 字符串。
  3. 货币：涉及 currency 的 tool 必须传 USD 或 CNY（大写）。
  4. 写操作：必须 "confirm": true；MCP 无 dry-run，生产环境勿试探性调用写 tool。
  5. 缺参：返回结构化参数说明，含必填项表格。

10. 写操作安全​

用户确认 → MCP tool（confirm=true）→ WriteGuard → PostOnce（不重试）→ 回读 → 审计日志
机制说明
confirm=true每次写调用必填；用户在对话里明确同意后，由 Agent 写入 tool 参数，无需手写 JSON
MCP_ENABLE_WRITES服务端环境变量；false 时拒绝所有写 tool
无自动重试避免重复创建
WRITE_AUDIT服务端审计日志

提示词示例（写前）：先 summarize_app_configuration 核对 app_uuid 并说明将改字段；用户回复「确认执行」后，再调用 upsert_placement 且参数含 confirm: true。

11. 典型对话场景​

11.1 账号与权限巡检​

  • 请用 summarize_current_access 总结我当前账号能看到哪些应用和资源。
  • 请检查我是否能访问广告位 <adseat_uuid>，currency 用 USD。

11.2 应用 / 广告位 / 广告源​

  • 列出我账号下所有应用。
  • 查询应用 <app_uuid> 下所有广告位。
  • 查询广告位 <adseat_uuid> 下 USD 的所有广告源，包含已关闭的（is_on 为 -1）。

11.3 报表​

  • 查询 2026-05-01 到 2026-05-07 的 V4 报表，按 date 和 adsourceId 分组，指标 revenue、impression、fillTime。
  • 查询应用 <app_uuid> 在 2026-05-01 至 2026-05-07 的用户价值曲线（query_ltv_report，metrics 用 all）。
  • 查询 2026-05-01 当天应用 <app_uuid> 的设备层级报表下载链接（query_device_report）。
  • 查询应用 <app_uuid> 在 2026-05-01 至 2026-05-07 的广告漏斗（query_funnel_report）。
  • 按中介组 <group_id> 查询广告位 <adseat_uuid> 的 SDK 事件汇总（query_sdk_event_log）。

11.4 中介组排序​

  • 先用 list_intermediary_groups 列出广告位 <adseat_uuid> 在 bucket 0 下的自定义组，再调用 reorder_intermediary_groups 把目标组调到最高优先级（须用户确认后 confirm: true）。

11.5 平台授权与自动化创建​

  • 列出已授权的广告平台 API token。
  • 查询 adsource_id=2（AdMob）的授权字段模板。
  • 自动化创建：使用 upsert_placement，传 is_auto_create=1、placement_config 等；具体字段以调用时返回的参数说明表为准。

12. 常见问题​

12.1 missing TradPlus Bear / missing TradPlus Secret​

检查 .cursor/mcp.json 的 headers 是否填写 X-TradPlus-Bear、X-TradPlus-Secret，修改后 刷新 MCP。

12.2 403 / sign error​

Secret 错误或缺失；确认 Bear 与 Secret 来自同一 API Key。

12.3 1001 货币单位错误​

list_placements 等未传 currency，或值不是 USD/CNY。

12.4 报表 tool 报错或数据为空​

  • 确认日期范围、应用 UUID 是否正确，账号是否有报表权限。
  • 若配置查询正常而报表失败，可能是服务地址未配对；使用官方 MCP 入口时一般由服务端自动处理，自建环境请联系技术支持。

12.5 Agent 没有调用任何 tool​

  • 确认 MCP 在客户端中已连接。
  • 描述中写明动作（查询、列出、汇总）和资源 ID。
  • 可明确要求：「请使用 TradPlus MCP 的 list_apps」。

12.6 写操作被拒绝​

  • 是否传了 "confirm": true（须由 Agent 写入 tool 参数；用户口头确认不够，需明确说「确认执行」或让 Agent 设置 confirm: true）。
  • 服务端是否 MCP_ENABLE_WRITES=false。
  • 高风险 start_abtest / close_abtest 是否已充分评估对线上流量的影响。

13. 获取帮助​

需求建议
某 tool 有哪些参数对话中少传参数触发说明表
不确定下一步调用 get_usage_guide 或 list_workflows