Skip to main content

TradPlus MCP 使用说明

修订历史​

发布时间修订说明
2026-09-18upsert_placement 支持 start.io（28）、GAM（48）、Verve（53）手工创建（不含自动化）；query_v4_report 的 group_by 支持 intermediaryGroupId（按中介组拆行，与 group_id 过滤不同）
2026-09-14自定义中介组更新未传 cache_num 时沿用该组已有并行数，不再改成广告类型默认；未传 min_cache 保持原值。创建未传 cache_num 仍按类型默认。
2026-09-11独立绿字段写清取值：发布地区、超时单位与权限、频控 0=不限制 / 1–1000、开屏重试 0 关 1 开、组底价需公司二级（中级）/三级（高级）/九级（默认）；更新未传保持原值
2026-09-11写 tool 补齐联动校验：上架与安卓市场、展示回调类型、填充回调与等待时长、自动刷新、最小缓存、竞价底价、创建时 is_modify_pid；广告源 group_list 传入须全量覆盖。缺参说明与 tool schema 对齐：密钥系统生成、更新用 refresh_secret_key / refresh_imp_secret_key、group_list 更新省略不改开关
2026-09-10广告位回调密钥由系统生成；编辑用 refresh_secret_key / refresh_imp_secret_key=1 换新密钥
2026-09-04create_adseat / new_get_adsource_list 的 ad_type 支持互动（7）、插播（8）。cache_num 创建仍必填：互动请传 1，不要套 2；插播传 2
2026-09-02应用/广告位/中介组/广告源对齐开发者后台绿字段；补齐 list 回显、create/update 参数表、group_list 对不上报错不改库、is_modify_pid 冲突
2026-08-20upsert_placement 支持 Moloco（82）、Magnite（83）手工创建（不含自动化）；PID 与样式见 ssp_api 附录2
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低创建/更新广告位。激励可配奖励回调（开时传 callback_url，密钥系统生成）；各类型可配展示回调。编辑可 refresh_secret_key / refresh_imp_secret_key=1 换新密钥。查询列表明文回显
update_app低更新应用，可改 is_release/domain/other_app_market/app_release_region；2/3 须有域名和商店链接，未传则沿用库里已有值。Android 已上架须市场 13，其他市场须 0–12
create_app / delete_app中创建/删除应用。创建须传 is_release（1/2/3）；2/3 还须 domain 与 app_url。还可传 other_app_market、app_release_region。Android 已上架须 other_app_market=13
upsert_placement / toggle_placement中创建/更新/启停广告源。Fyber（24）自动化需 placement_config.appId 且不支持 Header Bidding；YSO（77）自动化需 auto_app_id、开启 Header Bidding 且仅 S2S（header_bidding_type=0）；zMaticoo（55）手工创建需 AppKey+placementId；Moloco（82）/ Magnite（83）/ 国内穿山甲（17）/ start.io（28）/ GAM（48）/ Verve（53）仅手工创建。还可传 group_list（传入须全量覆盖，[] 会全关）、bidding_floor_price（仅竞价源）、is_modify_pid（仅更新）。group_list 对不上会报错且不改库；is_modify_pid 冲突见 §8.19
update_api_token / save_authorization_info中授权相关
upsert_intermediary_group中中介组。可写超时、填充回调、频控、开屏失败重试、横幅刷新；类型不对或无权限会报错。字段见 §8.18
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每页条数

返回 app_list，每条含 app_uuid / app_name / os / is_release（1 未上架 2 已上架 3 其他应用市场）/ domain / other_app_market / app_release_region / package_name / app_url / category_id。

8.2 list_adseats​

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

返回 adseat_list。ad_type：1 原生 / 2 插屏 / 3 开屏 / 4 横幅 / 5 激励 / 7 互动 / 8 插播。激励含奖励回调 is_server_callback / callback_url / secret_key（系统生成，明文只读）；各类型可含展示回调 imp_is_server_callback / imp_callback_url / imp_secret_key（系统生成，明文只读）/ imp_callback_type。

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}

返回 placements。中介组关系在 intermediary_group（不含广告位数字 adseat_id）。

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。按中介组拆行用 intermediaryGroupId（例 date,intermediaryGroupId）。该维下广告网络 API 指标不返回，请用 request / impression / eventRevenue 等 TradPlus 统计
app_uuidsStringN逗号分隔
adseat_uuidsStringN逗号分隔
group_idIntN中介组过滤；可传 0 表示默认组。与 group_by=intermediaryGroupId（拆行）不是同一参数

说明：fillTime 为综合报表填充时长，不等于中介管理「应用层面」请求/填充导出。group_id 是过滤中介组内广告源；要按中介组拆行须在 group_by 中带 intermediaryGroupId。按中介组过滤请用 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 激励 / 7 互动 / 8 插播
osIntY1 Android / 2 iOS

8.15 写操作通用​

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

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

手工创建 placement_config（is_auto_create 省略或 0）：

  • Moloco（adsource_id=82）：appkey + placementId；不支持 is_auto_create=1。普通横幅须 ad_size（1=320×50，2=300×250，3=728×90）；开屏可按 is_native 回填 placement_ad_type；Header Bidding 仅 S2S（is_header_bidding=1，勿传 header_bidding_type=1）。样式见 ssp_api 附录2。
  • Magnite（adsource_id=83）：appId + accountId + siteId + placementId；不支持 is_auto_create=1。普通横幅须 ad_size；原生插屏填 adsource_type（1=全屏 / 2=半屏）；勿传 is_template_rendering；原生横幅不要传 ad_size。Header Bidding 仅 S2S。同应用可先 get_placement_list_by_app 复用 appId/accountId/siteId。
  • start.io（adsource_id=28）：appId + placementId；须 is_header_bidding=1（仅 S2S）；不支持 is_auto_create=1。普通横幅 is_native=0 须 ad_size（1=320×50，2=300×250），不适用 native_ad_size、close_button。原生横幅 is_native=1 须 native_ad_size（1=320×50，2=320×100，3=300×250，4=728×90）和 close_button（1=显示，2=隐藏，默认 2），不适用 ad_size。原生插屏 is_native=1 须 adsource_type（1=全屏 / 2=半屏）。开屏：原生开屏传 is_native=1 且 placement_ad_type=1；插屏开屏传 is_native=0 且 placement_ad_type=2。Android 插屏开屏另须 ad_format（1=插屏视频，2=插屏图片），缺失返回 ad_format样式配置参数缺失；iOS 和原生开屏传 ad_format 返回 ad_format配置参数错误。
  • GAM（adsource_id=48）：placementId 必填；Android 另须非空 appId，iOS 可省略或空串。不支持 is_auto_create=1 与 Header Bidding。普通横幅 is_native=0 须同时填 ad_size（1=320×50，2=320×100，3=300×250，4=468×60，5=728×90，6=adaptive banners）和 collapsible（0=否 / 1=顶部 / 2=底部）；缺 collapsible 返回 collapsible样式配置参数缺失。原生横幅 is_native=1 须 ad_size 素材比例（1=未指定，2=任意尺寸，3=横屏尺寸，4=竖屏尺寸，5=正方形尺寸）、native_ad_size（1=320×50，2=320×100，3=300×250，4=728×90）和 close_button（1=显示，2=隐藏，默认 2），不适用 collapsible。标准原生：banner_mrec=1 时须 ad_size 素材比例（1–5）；banner_mrec=4（MREC）不传 ad_size，服务端写入 3。插播广告须 video_protocol（1=VAST，2=VMAP），缺失返回 video_protocol样式配置参数缺失，非 1/2 返回 video_protocol配置参数错误。激励须 adsource_type（1=激励视频 / 2=插页式激励）。横幅 is_native=99 为内嵌式自适应，不传 ad_size、collapsible。
  • Verve（adsource_id=53）：appId + appToken + placementId；须 is_header_bidding=1（仅 S2S）；不支持 is_auto_create=1；公司须开通 Verve 权限。普通横幅 is_native=0 须 ad_size（1=320×50，2=300×250，3=728×90）。原生横幅 is_native=1 无 ad_size、native_ad_size、close_button、collapsible。开屏传 is_native=1。

不确定步骤时，先 get_usage_guide（workflow=moloco_manual_adsource、magnite_manual_adsource、startio_manual_adsource、gam_manual_adsource 或 verve_manual_adsource）。绿字段参数见下列各节。

8.16 create_app / update_app​

须 "confirm": true。

字段类型必传说明
app_uuidString更新 Y仅 update_app
app_nameString创建 Y最长 100
osInt创建 Y1 Android，2 iOS
is_releaseInt创建 Y1 未上架 2 已上架 3 其他应用市场；更新可选。2/3 须有 domain 与 app_url：创建必传；更新未传则沿用库里已有值。Android：2 须 other_app_market=13，3 须 0–12
domainStringN*is_release=2/3 时须有值。更新未传则沿用已有域名
other_app_marketIntN仅 Android。is_release=2 须为 13（Google Play）；=3 须 0–12 且不能是 13。13 时会按商店链接拉元数据
app_release_regionIntN1 全球地区、2 中国地区、3 海外地区。更新未传则保持原值
package_name / category_id—N*无 app_url 时创建必填
app_urlStringN商店链接

示例：{"app_name":"Demo","os":1,"is_release":1,"package_name":"com.example.app","category_id":101,"confirm":true}

8.17 create_adseat / update_adseat​

须 "confirm": true。更新须 app_uuid + adseat_uuid。

字段类型必传说明
ad_typeInt创建 Y1 原生 / 2 插屏 / 3 开屏 / 4 横幅 / 5 激励 / 7 互动 / 8 插播；创建后不可改
cache_numInt创建 Y开屏 1–5，其他 1–20。互动请传 1，不要套 2；插播传 2
is_server_callbackIntN仅激励；1=开须 callback_url。密钥系统生成，查询明文回显。非激励传奖励回调会报「非激励视频无需设置奖励回调」
callback_urlStringN奖励回调 URL
refresh_secret_keyIntN仅更新；1=换新奖励回调密钥
imp_is_server_callbackIntN各类型均可；1=开须 imp_callback_url。密钥系统生成
imp_callback_urlStringN展示回调 URL
refresh_imp_secret_keyIntN仅更新；1=换新展示回调密钥
imp_callback_typeIntN1 普通 2 精准。只要传了且不是 1 或 2（如 99），无论回调开或关都报「展示回调类型参数设置错误」。0 或不传不报错

开屏另需 skip_time / countdown_time / is_skip；其余创建字段见缺参时的参数说明表。密钥用 list_adseats 回显。

创建激励并打开奖励回调：{"app_uuid":"<app_uuid>","seat_name":"激励01","ad_type":5,"cache_num":2,"is_server_callback":1,"callback_url":"https://example.com/reward","confirm":true}

换奖励回调密钥：{"app_uuid":"<app_uuid>","adseat_uuid":"<adseat_uuid>","refresh_secret_key":1,"confirm":true}

8.18 upsert_intermediary_group​

须 "confirm": true。group_id 省略=新建；0=更新兜底组。

字段类型必传说明
adseat_uuid / group_name / bucket_id / currency—Y与 ssp_api 中介组 store 相同
cache_numIntN并行请求数，上限 20。更新未传沿用该组已有值；创建未传按广告类型默认（开屏/互动 1，其他 2）
min_cacheIntN最小缓存数；不能大于本次将写入的 cache_num（更新未传并行数时按该组已有值）。更新未传保持原值
sdk_request_adsource_timeout / sdk_bidding_timeoutIntN单位秒。需公司开通 request_ad_timeout 权限，否则报「没有权限设置SDK请求超时」。更新未传保持原值
sdk_c2s_bidding_timeoutIntN单位秒。不需要 request_ad_timeout 权限。更新未传保持原值
sdk_load_max_wait_timeIntN单位秒；0=不设等待。速度优先（ad_fill_callback=2）不能带正数等待。未传填充回调或 =1 时可大于 0
ad_fill_callbackIntN1=eCPM 优先，2=速度优先。需公司级别为三级（高级）或九级（默认）；一级（初级）、二级（中级）会报「没有权限设置广告填充回调」
frequency_capping_hourIntN每小时展示上限。0=不限制；1–1000=次数。更新未传保持原值
frequency_capping_dayIntN每天展示上限。0=不限制；1–1000=次数。更新未传保持原值
frequency_pacing_minIntN展示间隔，单位分钟。0=不限制；1–1000=分钟。更新未传保持原值
request_fail_retryIntN仅开屏。0=关，1=开。其他类型会报「request_fail_retry不适用于当前广告类型」
is_refresh / refresh_timeIntN仅横幅。开须带时长 5–180；关时不要同时传时长
bidding_floor_priceStringN组底价，单位与 currency 一致。0=不设底价。需公司级别为二级（中级）、三级（高级）或九级（默认）；一级（初级）会报「没有权限设置中介组Bidding底价」

独立字段互不联动：ident 仍要带，只加要改的键。例如只改每小时上限：{"adseat_uuid":"<uuid>","group_id":56657,"bucket_id":0,"group_name":"自定义","currency":"USD","is_preset":0,"is_cold_scene":0,"frequency_capping_hour":10,"confirm":true}

横幅自定义组并行数已是 10、最小缓存已是 8 时，上面这条不传 cache_num 的调用会保持 10 和 8，不会把并行数改成类型默认 2。

list_intermediary_groups 返回上述绿字段（无默认组行时可能只有占位字段，写入后带回完整键）。

8.19 upsert_placement 绿字段​

须 "confirm": true。创建/更新通用字段见 §8.15 与缺参说明表。

字段类型必传说明
group_listArrayN传入则必须传全量（含空数组）。[] 会关掉该广告源下全部组。每项含 group_id、bucket_id、adseat_id（数字 ID，不是 uuid）。可选 selected（1=开启，不传默认 1；0=关闭）、rate（排序价格，不传默认 0，单位与 currency 一致）、is_auto_price（不传默认 0）。对不上报错、不改库。通过后先全关再按列表恢复；漏传的组会被关掉。省略则创建时加入全部组、更新时不改组开关
bidding_floor_priceStringN仅 Header Bidding 广告源可写。单位与 currency 一致。非 ADX 需权限，否则报错；TradPlus ADX / SAAS ADX 无权限时按 0 写入。更新未传保持原值
is_modify_pidIntN仅更新；创建传 1 会报错。1=跨广告位同步 PID，需 modify_placement。旧 PID 与新 PID 均已被其他广告位占用时返回「广告位下已存在相同广告源参数」，本条不写库

更新时 tool 会先按「仅开启」查询 placement_id；已关闭源须先 list_placements 带 is_on=-1 确认 ID。

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。
  • 查询 2026-05-01 到 2026-05-07 的 V4 报表，按 date 和 intermediaryGroupId 拆行（中介组维度，与 group_id 过滤不同）。
  • 查询应用 <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 等；具体字段以调用时返回的参数说明表为准。
  • Moloco 手工创建：get_usage_guide(workflow=moloco_manual_adsource)，再 upsert_placement（adsource_id=82，is_auto_create 省略，placement_config 含 appkey+placementId，confirm: true）。
  • Magnite 手工创建：get_usage_guide(workflow=magnite_manual_adsource)，再 upsert_placement（adsource_id=83，placement_config 含 appId+accountId+siteId+placementId，confirm: true）。勿传 is_auto_create=1。
  • start.io 手工创建：get_usage_guide(workflow=startio_manual_adsource)，再 upsert_placement（adsource_id=28，is_header_bidding=1，placement_config 含 appId+placementId，confirm: true）。
  • GAM 手工创建：get_usage_guide(workflow=gam_manual_adsource)，再 upsert_placement（adsource_id=48，placement_config 含 placementId，Android 另含 appId，confirm: true）。
  • Verve 手工创建：get_usage_guide(workflow=verve_manual_adsource)，再 upsert_placement（adsource_id=53，is_header_bidding=1，placement_config 含 appId+appToken+placementId，confirm: true）。

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