TradPlus 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 对象，字段名与 OpenAPI 一致（snake_case）。
凭证由客户端提供：服务端不保存你的 API Key；每次请求通过 Header 传入 X-TradPlus-Bear / X-TradPlus-Secret。
写操作有闸门：写类 tool 必须传 confirm=true；服务端还可通过 MCP_ENABLE_WRITES=false 切为只读。

各 tool 的业务字段以 OpenAPI 约定为准；缺参时由服务返回参数说明表。本文说明 如何接入 MCP、如何调用 tools、常见排错。

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`
MCP SSE 入口	`https://mcp.tradplusad.com/sse`

MCP 服务进程侧通过 TRADPLUS_BASE_URL 指向上述 OpenAPI 根地址（由服务部署配置，不是 tool 参数）。

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

7. 工具索引

当前约 50 个 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 只读：报表

tool	说明
`query_v4_report`	通用 V4 报表
`query_v4_api_report`	三方 API 维度报表
`query_v4_tp_report`	TradPlus 平台报表
`query_v4_abtest_report`	AB 测试报表
`query_v4_app_forecast_report`	应用预估
`query_v4_ab_confidence_report`	AB 置信度
`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`	常见问题

不确定用哪个 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`
group_by	String	N	如 `date,adsourceId`
app_uuids	String	N	逗号分隔
adseat_uuids	String	N	逗号分隔

8.8 `new_get_adsource_list`

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

8.9 写操作通用

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

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

9. 参数约定

字段名：snake_case，与 OpenAPI 一致（app_uuid、adseat_uuid、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。

11.4 平台授权与自动化创建

列出已授权的广告平台 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 Agent 没有调用任何 tool

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

12.5 写操作被拒绝

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

13. 获取帮助

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

修订历史​

1. 简介​

2. 适用场景​

3. 获取凭证​

4. 服务地址​

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 new_get_adsource_list​

8.9 写操作通用​

9. 参数约定​

10. 写操作安全​

11. 典型对话场景​

11.1 账号与权限巡检​

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

11.3 报表​

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

12. 常见问题​

12.1 missing TradPlus Bear / missing TradPlus Secret​

12.2 403 / sign error​

12.3 1001 货币单位错误​

12.4 Agent 没有调用任何 tool​

12.5 写操作被拒绝​

13. 获取帮助​