TradPlus MCP 使用说明

修订历史

发布时间	修订说明
2026-07-03	对齐 MCP/CLI v0.17.0-release；更新工具数量与漏斗、SDK 事件 tool 索引
2026-07-02	补充管理 API 与报表 OpenAPI 双后端、服务端环境变量与完整报表 tool 索引
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 切为只读。
双后端自动路由：配置类接口走管理 API（Bear + Secret + sign）；多数报表走报表 OpenAPI（仅 Bearer）。客户端无需在 tool 参数里填写 URL，部署侧通过 TRADPLUS_BASE_URL / TRADPLUS_REPORT_BASE_URL 配置（见 §4）。

各 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 能力拆分为 管理 API 与 报表 OpenAPI 两个网关。MCP / CLI 会根据 tool 自动路由；客户端只需在 Header 中提供凭证，无需在 tool 参数里填写 URL。

用途	生产地址	测试地址（示例）
管理 API（应用、广告位、广告源、漏斗/SDK 事件等）	`https://api-developer.tradplusad.com`	`https://test-2-api-developer.tradplusad.com`
报表 OpenAPI（v3/v4 综合报表、LTV、cohort 等）	`https://openapi.tradplusad.com`	`https://test-openapi.tradplusad.com`
MCP SSE 入口	`https://mcp.tradplusad.com/sse`	以运维提供的测试 MCP 地址为准

鉴权差异：

网关	鉴权	典型路径
管理 API	Bear + Secret + sign	`/api/App/apps`、`/api/V2/funnelReport`
报表 OpenAPI	仅 Bearer	`/v4/allreport`、`/v2/ltv`

4.1 服务端环境变量（部署侧）

下列变量由 MCP 服务进程读取，不是 tool 业务参数：

变量	说明
`TRADPLUS_BASE_URL`	管理 API 根地址
`TRADPLUS_REPORT_BASE_URL`	报表 OpenAPI 根地址；未设置时按 `TRADPLUS_BASE_URL` 推断（测试网关 → `test-openapi`，否则 → `openapi`）
`MCP_ENABLE_WRITES`	`false` 时拒绝所有写 tool

HTTP/SSE 模式下，Bear/Secret 由客户端 Header 传入；stdio 模式下还可使用 TRADPLUS_BEAR / TRADPLUS_SECRET 环境变量。

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`
查看某应用的配置总览（需提供 app_uuid）	`summarize_app_configuration`

7. 工具索引

当前约 66 个 MCP tools，按类别列出。调用时传入 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_detail`	Token 详情
`get_account_template`	平台授权字段模板

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

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

7.4 只读：报表

综合与 cohort 报表多数走 报表 OpenAPI；漏斗、SDK 事件、活跃用户等走 管理 API 开发者网关。路径细节见数据报表查询 API 与 tp_cli §3.4。

tool	上游（生产示例）	说明
`query_v4_report`	`POST …/v4/allreport`	综合报表（日常首选）；支持 `fetch_all` 分页
`query_v3_report`	`POST …/v3/allreport`	V3 综合报表（兼容）
`query_v4_api_report`	`POST …/v4/apireport`	三方 API 维度（单日）
`query_v4_tp_report`	`POST …/v4/tpreport`	TradPlus 统计维度（单日）
`query_ltv_report`	`POST …/v2/ltv`	用户价值 1–90 天（广告网络数据）
`query_tpltv_report`	`POST …/v2/tpltv`	用户价值 1–90 天（TradPlus 统计）
`query_user_retention_report`	`POST …/v2/userActive`	用户留存 2–90 天
`query_ltv_imp_report`	`POST …/api/V2/ltvImp`	用户 LTV 展示 1–90 天（TradPlus 统计）
`query_user_arpu_report`	`POST …/v2/userArpu`	新增用户 ARPU 1–90 天
`query_user_imp_report`	`POST …/v2/userImp`	新增用户人均展示 1–90 天
`query_user_ecpm_report`	`POST …/v2/userEcpm`	新增用户 eCPM 1–90 天
`query_user_type_report`	`POST …/api/V2/userTypeReport`	新老用户日维度指标
`query_deu_retention_report`	`POST …/api/V2/userDeu`	DEU 留存渗透率
`query_device_report`	`POST …/v4/deviceReport`	设备层级报表 CSV 下载链接
`query_v4_abtest_report`	`POST …/v4/abtestreport`	A/B 测试报表
`query_v4_app_forecast_report`	`POST …/v4/appforecastreport`	应用预估
`query_v4_ab_confidence_report`	`POST …/v4/abconfidencereport`	A/B 置信度
`query_active_user_report`	`POST …/api/ActiveUserReport/allreport`	DAU/DEU（开发者网关）
`query_funnel_report`	`POST …/api/V2/funnelReport`	广告漏斗
`query_sdk_event_log` / `query_sdk_event_log_detail`	`POST …/api/V2/sdkEventLog*`	SDK 事件分析

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 各平台下载地址

不确定用哪个 tool 时，可先调用 get_usage_guide 或 summarize_current_access。

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`	中	中介组
`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_uuids	String	N	逗号分隔，最多 100；有则忽略分页
page	Int	N	默认 1
limit	Int	N	每页条数

8.2 `list_adseats`

字段	类型	必传	说明
app_uuid	String	N*	与 `adseat_uuids` 二选一
adseat_uuids	String	N*	逗号分隔
page	Int	N	默认 1

8.3 `list_placements`

字段	类型	必传	说明
currency	String	Y	`USD` 或 `CNY`；漏传报 `1001`
adseat_uuids	String	N	逗号分隔
app_uuids	String	N	逗号分隔
adsource_ids	String	N	逗号分隔
placement_ids	String	N	逗号分隔
is_on	Int	N	`0` 关 / `1` 开 / `-1` 全部
page	Int	N	默认 1

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

8.4 `validate_access_scope`

字段	类型	必传	说明
app_uuid	String	N*	与 `adseat_uuid` 至少传一个
adseat_uuid	String	N*	与 `app_uuid` 至少传一个
currency	String	N	默认 `USD`

8.5 `summarize_app_configuration`

字段	类型	必传	说明
app_uuid	String	Y	应用 UUID
currency	String	N	`USD` / `CNY`，默认 `USD`

8.6 `summarize_adseat_overview`

字段	类型	必传	说明
adseat_uuid	String	Y	广告位 UUID
currency	String	Y	`USD` 或 `CNY`

8.7 `query_v4_report`

字段	类型	必传	说明
start_date	String	Y	`YYYY-MM-DD`
end_date	String	Y	`YYYY-MM-DD`
metrics	String	N	如 `revenue,impression,click`；默认 `all`
preset	String	N	如 `dashboard-placement-source`（与 `metrics=all` 同用时忽略 `all`）
group_by	String	N	如 `date,adsourceId`
app_uuids	String	N	逗号分隔
adseat_uuids	String	N	逗号分隔；映射 `placementIdList`
group_id	Int	N	中介组 ID
start	Int	N	分页偏移
limit	Int	N	每页条数，最大 20000
fetch_all	String	N	传 `true`/`1` 自动拉全量
page	Int	N	兼容旧参数，转换为 `start`

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

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

字段	类型	必传	说明
start_date	String	Y	`YYYY-MM-DD`
end_date	String	Y	`YYYY-MM-DD`
metrics	String	N	逗号分隔；默认 `all`（如 `ltv1,ltv7`、`kp1,kp7`、`arpu1`）
group_by	String	N	逗号分隔；默认 `date,app`；用户价值类可含 `placementId`，留存与 DEU 类不可按广告位聚合
app_uuids	String	N	应用 UUID，逗号分隔
areas	String	N	国家代码，逗号分隔
channels	String	N	渠道，逗号分隔
app_versions	String	N	应用版本，逗号分隔
placement_ids	String	N	广告位 UUID，逗号分隔（筛选；留存/DEU 不可写入 `group_by`）
currency	String	N	`USD` 或 `CNY`
timezone	String	N	`UTC+0` / `UTC+8` / `UTC-8`

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

8.9 `query_user_type_report`（新老用户）

字段	类型	必传	说明
start_date	String	Y	`YYYY-MM-DD`
end_date	String	Y	`YYYY-MM-DD`
app_uuids	String	N	应用 UUID，逗号分隔
user_types	String	N	`1` 新用户、`2` 老用户，逗号分隔
channels	String	N	渠道过滤
areas	String	N	国家代码
currency	String	N	`USD` 或 `CNY`

8.10 `query_device_report`（设备层级报表）

字段	类型	必传	说明
date	String	Y	单日 `YYYY-MM-DD`
app_uuid	String	Y	应用 UUID
api_version	String	N	`v3` 或 `v4`，默认 `v4`
timezone	String	N	`UTC+0` / `UTC+8` / `UTC-8`
currency	String	N	`USD` 或 `CNY`

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

8.11 `new_get_adsource_list`

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

8.12 写操作通用

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

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

9. 参数约定

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

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。
拉取上述日期段 V4 全量数据（自动分页），preset 用 dashboard-placement-source。
查询应用 <app_uuid> 在 2026-05-01 至 2026-05-07 的用户价值曲线（query_ltv_report，metrics 用 all）。
查询 2026-05-01 当天应用 <app_uuid> 的设备层级报表下载链接（query_device_report）。

11.4 漏斗与 SDK 事件（开发者网关）

查询应用 <app_uuid> 在 2026-05-01 至 2026-05-07 的广告漏斗汇总（query_funnel_report，view=summary）。
查询广告位 <adseat_uuid> 的 SDK 事件汇总（query_sdk_event_log）。

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 写操作被拒绝

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

12.5 报表返回 404 或 `report api call failed`

确认 MCP 服务端 TRADPLUS_REPORT_BASE_URL 与当前环境一致（生产 openapi，测试 test-openapi）。
query_v4_report 等走报表 OpenAPI；query_active_user_report / query_funnel_report 等走管理 API，勿混用地址。
测试环境若报表 OpenAPI 尚未部署某路径，请联系运维或暂时使用开发者网关等价接口（如 /api/V4/allreport）。

12.6 Agent 没有调用任何 tool

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

13. 获取帮助

需求	建议
某 tool 有哪些参数	对话中少传参数触发说明表；或对照 tp_cli.md §8
终端批量查报表	使用 tp_cli.md §7.5
不确定下一步	调用 `get_usage_guide` 或 `list_workflows`

修订历史​

1. 简介​

2. 适用场景​

3. 获取凭证​

4. 服务地址与双后端​

4.1 服务端环境变量（部署侧）​

5. 接入方式​

5.1 HTTP/SSE​

6. 验证 MCP 是否生效​

7. 工具索引​

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

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

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

7.4 只读：报表​

7.5 聚合与权限​

7.6 Agent 引导​

7.7 写操作（需 confirm=true）​

8. 常用 tool 参数​

8.1 list_apps​

8.2 list_adseats​

8.3 list_placements​

8.4 validate_access_scope​

8.5 summarize_app_configuration​

8.6 summarize_adseat_overview​

8.7 query_v4_report​

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

8.9 query_user_type_report（新老用户）​

8.10 query_device_report（设备层级报表）​

8.11 new_get_adsource_list​

8.12 写操作通用​

9. 参数约定​

10. 写操作安全​

11. 典型对话场景​

11.1 账号与权限巡检​

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

11.3 报表​

11.4 漏斗与 SDK 事件（开发者网关）​

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

12. 常见问题​

12.1 missing TradPlus Bear / missing TradPlus Secret​

12.2 403 / sign error​

12.3 1001 货币单位错误​

12.4 写操作被拒绝​

12.5 报表返回 404 或 report api call failed​

12.6 Agent 没有调用任何 tool​

13. 获取帮助​