工具参考
CloudX MCP 当前公开 17 个工具：七个报表工具、四个竞价检查工具、五个配置工具与一个文档检索工具。已认证用户始终只能访问自己的 CloudX 账户。工具汇总
只读工具需要对应的
reports:read、auctions:read 或 configuration:read 权限。PostConfigEdit 与 PostConfigPublish 需要 configuration:write。报表工具参数
GetReportDashboard
用于跨时间范围的总体报表。
适用场景
- 总收入与填充率检查
- 每日趋势分析
- 按国家或平台快速健康检查
参数
响应结构
summarychart_data
summary 包含 total_requests、total_impressions、revenue、fill_rate、ecpm、total_clicks、ctr、total_users 等字段。
GetReportBreakdown
用于自行选择报表的分组维度与指标，而不是使用固定的 Dashboard 结构。
参数
响应结构
dimensions：请求的维度名metrics：请求的指标名rows：包含dimensions与metricsmap 的对象row_count
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
需要表格化数据而非汇总报表时使用此工具。
适用场景
- 将数据传入电子表格
- 校验下游分析
- 将结构化行交给其他工具或代理
参数
响应结构
columnsrowsrow_count
GetReportABTest
用于在指定时间范围内比较 A/B 测试的对照变体与测试变体。
时间范围不得超过 31 天。响应包含带累计指标与每日行的
control 和 test，以及可用时的 lift、p_value、chi_squared_p、置信区间、样本量和 status。
竞价检查工具
基于时间范围的竞价工具使用 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 使用美元 CPM 小数。
PostConfigPublish
将草稿发布为线上配置。body.draft_id 必填，body.version_label 可选。草稿上线前会执行与 CloudX 应用相同的服务端验证。响应包含 config_id、version_number 与 validation；阻断性验证失败会返回 MCP 错误，且不会发布。
SearchDocs
在 MCP 客户端中检索 CloudX 文档，在回答关于安装、配置、SDK、CLI、Dashboard、网络或报表的问题前使用。
适用场景
- 为某个 CloudX 工作流找到对应的文档页
- 在解释功能前以最新文档作为依据
- 不离开 AI 客户端即可获取相关的安装或排错片段
参数
工具调用结构
响应结构
results
content：匹配到的文档片段path：文档路径，例如/en/cli/reportingurl：绝对文档 URLmetadata：页面元数据（标题等，若可用）
错误行为
无法满足请求时，这些工具会返回 MCP 错误结果。常见原因：- 缺少
start_time或end_time - 枚举值无效，例如
device_os: "ios"而非iOS - 时间范围超过 31 天
- 竞价或配置 ID 不存在
- 没有请求工具所需的权限
- 配置编辑或发布验证失败
SearchDocs，空白或缺失的查询会返回 query is required。文档检索暂时不可用时，工具会返回 docs search error。