TradPlus MCP 使用说明
修订历史
| 发布时间 | 修订说明 |
|---|---|
| 2026-10-21 | 新增 query_hour_report:分小时报表。固定按小时返回,筛选不拆行;时间用 Unix 秒或带 timezone 的日期时间 |
| 2026-09-18 | upsert_placement 支持 start.io(28)、Google Ad Manager(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-04 | create_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-20 | upsert_placement 支持 Moloco(82)、Magnite(83)手工创建(不含自动化);PID 与样式见 ssp_api 附录2 |
| 2026-07-28 | 更新至 v0.21;SDK 事件明细支持查询已关闭源 |
| 2026-07-22 | 支持调整中介组优先级 |
| 2026-07-15 | SDK 事件支持按中介组过滤;报表支持填充时长;补充事件下钻说明 |
| 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 Key | X-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. 工具索引
当前 69 个 MCP tools(以服务端 HandlerMap 注册为准),按类别列出。调用时传入 JSON 对象 作为参数;写操作另需 "confirm": true。