每个公共 CloudX MCP 工具的参考，包括参数、支持的过滤器与响应字段。

工具参考

CloudX MCP 当前公开 24 个工具：八个报表工具、四个竞价检查工具、五个配置工具、六个任务工具与一个文档检索工具。已认证用户始终只能访问自己的 CloudX 账户。

工具汇总

报表工具参数

GetReportDashboard

用于跨时间范围的总体报表。

适用场景

• 总收入与填充率检查
• 每日趋势分析
• 按国家或平台快速健康检查

参数

响应结构

• summary
• chart_data

summary 包含 total_requests、total_impressions、revenue、fill_rate、ecpm、total_clicks、ctr、total_users 等字段。

GetReportBreakdown

用于自行选择报表的分组维度与指标，而不是使用固定的 Dashboard 结构。

参数

响应结构

• dimensions：请求的维度名
• metrics：请求的指标名
• rows：包含 dimensions 与 metrics map 的对象
• row_count

维度与指标的定义请参见 cloudx report breakdown。

GetReportBidders

用于对比需求合作伙伴。

适用场景

• 找出收入最高的竞价方
• 按合作伙伴检查竞价率与胜出率
• 跨国家或平台比较供给质量

参数

响应结构

• bidders

每个竞价方行可包含 name、requests、bids、bid_rate、impressions、win_rate、revenue 与 ecpm。

GetReportApps

用于在账户内比较应用级表现。

适用场景

• 按收入对应用排序
• 比较 iOS 与 Android 投放组合表现
• 发现填充率较低的应用

参数

响应结构

• apps

每个应用行可包含 app_id、name、platform、impressions、fill_rate、revenue 与 ecpm。

GetReportAdUnits

用于广告位级别的深入分析。

适用场景

• 比较 banner、激励视频与插屏广告
• 限定到单个应用 bundle
• 找出表现较弱或价值较高的广告位

参数

响应结构

• ad_units

每行可包含 ad_unit_id、name、app_name、app_bundle、type、impressions、fill_rate、revenue 与 ecpm。

GetReportExport

需要表格化数据而非汇总报表时使用此工具。

适用场景

• 将数据传入电子表格
• 校验下游分析
• 将结构化行交给其他工具或代理

参数

响应结构

• columns
• rows
• row_count

GetReportABTest

用于在指定时间范围内比较 A/B 测试的对照变体与测试变体。

时间范围不得超过 31 天。响应包含带累计指标与每日行的 control 和 test，以及可用时的 lift、p_value、chi_squared_p、置信区间、样本量和 status。

GetReportTotalRevenue

用于读取 Total Revenue 仪表板 所展示的发布商总收入报表，汇总 CloudX 与你在 Data Sources 中连接的聚合平台。

适用场景

• 发布商总收入与 CloudX 钱包份额
• 按应用、广告格式或国家比较各聚合平台
• 包含 CloudX 以外流量的每日收入趋势

参数

聚合平台报表每日同步。UTC 12:00 之前，数据完整至前天 UTC 日结束；UTC 12:00 起，完整至昨天结束。

响应结构

• totals：每个请求指标一个值
• series：每日数据点
• dimensionTables：每个请求维度一个表
• measures、dimensions、availableMeasures、availableDimensions
• startTime、endTime、requestedEndTime、dataCompleteThrough
• reportLink：指向仪表板中相同视图的链接

竞价检查工具

基于时间范围的竞价工具使用 Unix 秒时间戳，最大范围为 31 天。常用可选过滤器包括 test_mode、app_bundle、ad_unit_id、country 与 device_os。行数上限默认为 50，可设为 1–500。

GetAuctionList

用于在深入查看单次竞价前查找近期竞价。

has_ilrd 与 has_external_ilrd 不能同时使用。mediator 只能与 has_external_ilrd: true 一起使用。

auctions 响应数组包含 ID、时间戳、应用与广告单元上下文、获胜详情、出价计数、耗时、A/B 测试上下文与 ILRD 可用性。

GetAuctionShow

在已知竞价 ID 时使用。auction_id 必填；可选的 with 使用逗号分隔的 rounds、bids、ilrd、external-ilrd。响应中包含 auction_id、auctions 以及请求的关联数据。

GetAuctionRounds

使用 auction_id 检查单次竞价的轮次，或使用 start_time 与 end_time 聚合分析轮次。可选的 metric 为 distribution、duration、cleared-on 或 skip-reason，还支持常用流量过滤器与 limit。响应包含 rounds、metrics 或两者。

GetAuctionBids

用于检查指定时间范围内的出价与未出价行。start_time 与 end_time 必填，另支持常用流量过滤器、limit 以及 floor_source（static、dynamic、publisher 或 configured）。bids 数组包含竞价方、状态、价格、获胜、延迟、底价、拒绝原因与竞价上下文。

配置工具

GetConfigShow

不传参数时获取线上配置，也可使用 id、version 或 draft 选择草稿或已发布版本。响应包含 id、kind、版本与作者元数据、已解析的 data 与 yaml。

GetConfigValidate

不传参数时验证线上配置，也可使用 id 或 version 选择配置。响应包含 valid、error_count、warning_count、issues、source 与 yaml。

GetConfigHistory

按时间倒序列出近期配置行，最多 200 条，不代表账户的完整历史。可选参数为 since（RFC3339 或 YYYY-MM-DD）、author、include_drafts 与 limit（1–200，默认 50）。entries 包含配置 ID、类型、版本、作者、创建时间、描述与发布时 diff 计数。

PostConfigEdit

对应用、广告单元、广告单元组、账户竞价方、网络映射、列表、标签、测试设备、线项目或 A/B 测试应用类型化变更。

支持的操作包括：

• 应用：create_app、update_app、delete_app
• 广告单元：create_ad_unit、update_ad_unit、delete_ad_unit
• 网络与竞价方：upsert_network_mapping、delete_network_mapping、upsert_account_bidder
• 广告单元组：create_ad_unit_group、update_ad_unit_group、delete_ad_unit_group、remove_ad_unit_from_group
• 列表与标签：create_list、update_list、delete_list、create_tag、update_tag、delete_tag
• 测试设备：upsert_test_device、delete_test_device
• A/B 测试：create_ab_test、update_ab_test、start_ab_test、end_ab_test、promote_ab_test、delete_ab_test
• 线项目：create_line_item、update_line_item、delete_line_item

普通编辑与 create_ab_test 返回草稿。A/B 测试的更新、启动、结束、提升与删除操作会立即发布，且在请求中必须是唯一操作。底价在订单项上设置；创建和更新广告单元的操作不接受 bidfloor。订单项的 bidfloor 使用十进制 USD CPM。

PostConfigPublish

将草稿发布为线上配置。body.draft_id 必填，body.version_label 可选。草稿上线前会执行与 CloudX 应用相同的服务端验证。响应包含 config_id、version_number 与 validation；阻断性验证失败会返回 MCP 错误，且不会发布。

任务工具

通过 MCP 客户端管理定期运行的任务。任务按五字段 cron 表达式和 IANA 时区运行提示词。任务默认仅创建者可见；将 access_mode 设为 workspace 可与工作区共享。

创建任务时，省略 name 会根据提示词生成名称。timezone 默认为 UTC，enabled 默认为 true，access_mode 默认为 private。schedule 接受五字段 cron 表达式。更新时，省略的字段保持原值。只有创建者能将工作区任务改为私人任务。

任务对象包含 id、name、prompt、cron_expression、timezone、schedule_description、enabled、access_mode、next_run_at 和时间戳。列表响应将任务对象放在 scheduled_agents 中。

{
  "name": "CreateScheduledAgent",
  "arguments": {
    "body": {
      "prompt": "每周检查收入并标记显著变化",
      "schedule": "0 9 * * 1",
      "timezone": "Asia/Shanghai"
    }
  }
}

RunScheduledAgent 只能运行已启用且当前没有运行中执行的任务。有运行中执行的任务无法删除。

SearchDocs

在 MCP 客户端中检索 CloudX 文档，在回答关于安装、配置、SDK、CLI、Dashboard、网络或报表的问题前使用。

适用场景

• 为某个 CloudX 工作流找到对应的文档页
• 在解释功能前以最新文档作为依据
• 不离开 AI 客户端即可获取相关的安装或排错片段

参数

工具调用结构

{
  "name": "SearchDocs",
  "arguments": {
    "body": {
      "query": "report filters"
    }
  }
}

响应结构

• results

每条结果包含：

• content：匹配到的文档片段
• path：文档路径，例如 /en/cli/reporting
• url：绝对文档 URL
• metadata：页面元数据（标题等，若可用）

错误行为

无法满足请求时，这些工具会返回 MCP 错误结果。常见原因：

• 缺少 start_time 或 end_time
• 枚举值无效，例如 device_os: "ios" 而非 iOS
• 时间范围超过 31 天
• 竞价或配置 ID 不存在
• 没有请求工具所需的权限
• 配置编辑或发布验证失败

对于 SearchDocs，空白或缺失的查询会返回 query is required。文档检索暂时不可用时，工具会返回 docs search error。

相关链接

• 安装
• 示例