Documentation

Everything you need to connect AI agents to your ad accounts via MCP.

从一个账户的只读核对开始

读取已结束日期,查看缺失数据,再次打开原任务。首次体验不修改广告、预算或投放状态。

  1. 真实数据接入前,确认有权操作者、账户、客户端、体验安排、数据用途与保存,以及实际支持联系人。
  2. 在Portal登录自己的组织,按约定流程授权并选择账户,再使用所选客户端的原生远程MCP设置。
  3. 先发现客户端实际工具,再用gravityads.metrics.summary和source_policy=warehouse_only读取约定账户与日期。没有已存数据就说明缺口,不触发实时采集。

文字工具与交互App分别验收。对话中的只读要求不会降低凭据权限;key仅输入客户端私密设置,不放进共享文件或截图。

首次读取

只读取我已选择且获准的这个账户,使用约定的已结束日期,设置source_policy=warehouse_only。先给来源账户时区、币种及覆盖/缺失日期,再列可用指标。不调用广告API、不建定时任务、不改广告、不补缺失值;新采集或保存任务状态前先说明。
查看配置与请求示例

均为占位示例;账户和日期只替换为约定范围,不注入其他tenant或operator。

{
  "mcpServers": {
    "gravityads": {
      "url": "https://mcp.gravityads.dev/mcp",
      "headers": {
        "Authorization": "Bearer REPLACE_IN_PRIVATE_CLIENT_SETTINGS_ONLY"
      }
    }
  }
}
{
  "name": "gravityads.metrics.summary",
  "arguments": {
    "platform": "google",
    "account_id": "REPLACE_WITH_AUTHORIZED_ACCOUNT_ID",
    "start_date": "2026-01-01",
    "end_date": "2026-01-03",
    "days": 3,
    "granularity": "account",
    "source_policy": "warehouse_only"
  }
}
下载接入指南与示例

中文与English · ZIP

缺一天数据,不等于当天花费为零

合成示例,不是客户案例或广告平台官方导出。

请求3天,实际覆盖2天。来源自然日:Asia/Hong_Kong;币种:USD;没有重新分桶为UTC。

合成花费示例:两天分别观察到$40、$60,第三天标为缺失而不是零。
合成示例,不是客户案例或广告平台官方导出。
日期合成参考花费已观察花费已观察点击
2026-01-01$40$4020
2026-01-02$60$6030
2026-01-03$50缺失缺失

有记录的两天小计$100、50次点击。实际三天总计仍未知,完整期间对账未通过。

采取行动前,先核对报告

阅读全文

文中算例为合成数据,不是客户案例,也不证明广告效果提升。

报告中的数字正确,不代表回答了正确的问题。两天花费准确,不等于三天覆盖完整;账户自然日不一定等于UTC日;广告平台的转化价值,也不直接等于店铺收到的收入或利润。

用AI助手核对广告账户时,先看范围、覆盖和独立对照来源,再考虑建议是否可用。第一步应当是一份能解释、能重新打开的结果,而不只是一段听起来合理的优化意见。

先把问题限定清楚

明确一个获准账户、平台、已经结束的日期范围和币种,保留来源账户时区,以及平台归因和筛选设置。口径未知时应当直接说明,不能为了让两份结果看起来可比,自动补上未经确认的默认值。

首次任务可以很小:读取一个账户,列出可用指标,解释缺失。读取报告不等于授权改广告、预算或投放状态;创建保存任务也与广告写入不同,需要说明保存的状态。

小计不是完整期间总计

假设一个合成账户以USD、Asia/Hong_Kong自然日记账。请求1月1日至3日:参考表花费分别为$40、$60、$50,观察结果只有前两天,第三天没有记录。

此时可以说“有记录的两天花费小计$100”,不能说“三天总花费$100”。更不能把第三天补成$0,再判断账户停止投放。参考三天$150与已观察两天$100不是相同覆盖范围的期间指标。

在计算涨跌、CPA或ROAS之前,这个区别尤其重要。缺一天数据或缺少分母,可能生成外观完整、实际不支持结论的比率。保留缺失值,标明partial,指出下一步要核什么。本包算例把三天记录逐行展示,缺口没有藏在摘要后。

用独立来源核对

使用广告平台独立导出或后台结果,与相同账户、日期、时区、币种、归因和筛选的报告逐指标比较。记录差异、缺失与采用的容差;总数接近不能证明每天记录都相同。

同一个仓库换一个界面读取,可用于检查展示一致性,但不是独立平台对账。页面只显示几条预览,也不表示底层来源已经完整取齐;长证据通过原结果的正常分页或导出路径核查。

平台转化价值保留原标签;要称店铺收入、回款或利润,需要额外证据。也不要为了图表整齐,直接合并不同币种或把来源自然日重标为UTC。

恢复时沿用原结果

回答中断后,先重新打开同一保存任务和报告,核状态与已有证据,不要立刻创建一个替代任务。否则旧结果、新采集和重复操作很难区分。

明确只读已存数据时,对支持该参数的工具使用 source_policy=warehouse_only。缺数据就报告缺口,不自动回退实时广告查询;需要新采集时,另行说清账户和操作范围。对话文本既不会增加账户权限,也不能降低凭据本来拥有的权限。

分清停止访问与处置数据

产品断开、广告平台授权撤销、已存数据处置是三个动作。分别核对哪些新读取或采集已停止、哪些内容还保留,以及处置申请如何跟踪。申请提交不等于拿到了删除完成回执。

一次有用的首次体验应交付清楚的结果:哪些数值得到核对,哪些仍缺失,如何重新打开原报告,以及如何停止访问。之后再做一个用户真正需要的独立任务,判断它是否值得重复使用。

GravityAds MCP初期辅助只读范围按这一思路开展:读取已结束日期的账户指标,并返回已保存工作。平台、客户端和数据子范围按具体体验确认;文字工具与交互App界面分别验收,SDK成功不能外推所有客户端。完整自动巡检、广告写入与利润归因,不由一次账户指标读取自动放行。

下载教程

恢复时打开原任务和报告,不重建、不重新采集。产品断开、平台侧撤销与已存数据处置分别记录;申请提交不表示删除完成。

排障通过约定支持联系人提供时间、客户端版本、原任务引用及安全错误码;不要发送密码、key、Authorization请求头或原始客户导出。

Google Ads接入:只读权限到底指什么

Google登录成功只是一步。Google Ads账户角色、应用的平台准入、产品内账户权限,以及本次任务已有的数据,需要分别确认。

Google账户角色与OAuth同意

Google Ads的只读和读写操作使用相同的OAuth scope,用户能做什么由Ads账户角色决定。adwords不是专用只读scope;在对话中说“只读”也不会缩小这项授权。只通过约定的产品流程授权自己有权使用的账户,并核对Google同意页实际请求的范围。

应用准入要单独核对

Google Ads API的访问资格,与OAuth应用的发布或验证状态是不同事项,不能相互替代。本指南不认证某条连接当前已通过哪一项;以实际连接结果和约定的账户访问范围为准。

产品身份与账户权限

Portal组织、操作者、所选连接和获准广告账户应当一致。发现列表中能看到,不等于已获读取授权。平台登录不会自动给另一个组织访问权,运维人员的云登录也不是你的Google Ads产品授权。不要借同事账号或转发token来绕过拒绝。

已有数据与新采集

source_policy=warehouse_only只读取已有持久化数据,不会为新连接的账户采集数据。空白或partial可能表示约定日期尚无可用记录。保留来源账户自然日和币种;确需新采集时,先单独说明范围,再与Google Ads官方导出核对。

连接或读取失败时

先核明失败,再决定是否重新连接

访问或权限被拒绝

由有权负责人核对所选组织、账户和连接,请支持人员区分产品内权限、Google账户访问和应用准入。不要为消除报错直接扩大角色、scope或账户列表。

invalid_grant或刷新被拒绝

这表示当前授权不能续用,单凭错误不能判定具体原因。Google列出的可能原因包括撤销、过期及token数量限制;外部OAuth应用处于Testing时,还有七天刷新token期限规则,但官方列明的基础身份scope情形例外。不能由这个错误倒推你的连接就在Testing。先让支持人员确认安全错误类别;确需重新授权且有权账户持有人可操作时,再走正常产品流程。

连接成功,但指标缺失

核对已结束的日期、来源自然日、所选账户和已存数据覆盖。连接成功不是采集回执,也不证明每天都有记录。缺行继续标缺失,不补零,不暗中改成实时查询。

通过约定的私密支持渠道提供时间与时区、客户端版本、原任务引用和安全错误码。不要发送密码、一次性授权码、access/refresh token、API key、Authorization请求头或原始客户导出。

产品断开只停止该操作实际覆盖的访问路径;平台侧撤销和已存数据处置分别核实。重新打开已存报告不会续上已撤销的连接,提交处置申请也不表示已删除存储副本。

Google官方说明

来源核对日期:

返回首次只读任务

Meta Ads接入:从一个获准账户开始只读核对

先选一个获准广告账户和已经结束的日期。用Google或GitHub登录Portal,不等于同意Meta广告授权。本指南说明只读接入路径,不认证某条连接或本应用当前对所有账户都具备准入资格。

  1. 先核账户和有权授权的人

    在自己的Ads Manager中确认目标广告账户及自身访问资格,再在Portal核对所选组织并打开Connections。业务资产组合、公共主页或Instagram身份,不等于广告账户本身。本次只使用负责人明确允许核对的资产。

  2. 核对同意页实际范围

    产品的Meta只读连接请求ads_read;广告修改使用单独的ads_management路径。Meta区分Standard与Advanced Access,访问他人广告账户有相应准入要求。账户角色、已授permission和应用access level分别核实;不要为了读通就补ads_management,也不要把system-user token发给支持人员。

  3. 沿正常连接流程返回原组织

    使用所在组织可用的正常Meta连接流程,核对平台请求的访问范围后返回原Portal组织。读取前确认连接与获准广告账户。发现列表中可见,不等于产品内已授访问权;连接成功,也不证明报表数据已经到达。

  4. 读取一个完整期间并独立核对

    只读已存数据时,对支持该参数的工具使用source_policy=warehouse_only。保留来源时区、币种、购买事件、归因窗口及报告时间基准。Meta Insights分别提供购买相关字段,不叠加含义重叠的purchase别名。先用自己的Ads Manager导出核同口径,再把报告登记为已核对。

Meta访问或报表失败时

按失败环节排查

已返回产品,但账户缺失或被拒绝

由有权负责人核对原组织、连接和广告账户,请支持人员区分产品内权限、资产访问及应用准入。不要另建工作区、借身份或扩大权限来绕过拒绝。

授权过期、撤销或无法续用

保留安全错误码和原任务引用,先由支持人员确定失败类别;确需重新授权且有权人员可操作时,再走正常产品流程。不要把token贴到聊天,也不要在条件未变时反复重连。本指南不承诺固定token有效期。

读取成功,但缺日期或ROAS

新采集前先核所选账户、已存覆盖和原转化定义。缺购买价值不等于零收入;已覆盖日期小计不是完整期间总计,warehouse_only也不能暗中变成实时广告查询。

通过约定的私密支持渠道提供时间及时区、客户端版本、原任务引用和安全错误码。不要发送密码、一次性授权码、access/refresh token、API key、Authorization请求头或原始客户导出。

产品断开、平台撤销与已存数据处置分别核实:哪些新读取和采集已经停止,哪些内容仍保留。提交处置申请不表示所有存储或已下载副本都已删除。

Meta官方资料

来源核对日期:

返回首次只读任务

Microsoft Advertising接入:权限、账户与已有数据分开核

工具中可能显示Microsoft或Bing;核对真实平台与账户,不只看显示名称。Portal登录、广告同意、API访问资格和已存报表覆盖,是不同检查。

  1. 区分customer、account与产品组织

    在自己的Microsoft Advertising后台确认customer与account标识;界面中的account number不是API account ID。再在Portal核对本次组织及获准账户。发现列表可见,不会自动给另一个组织访问权。

  2. 看清OAuth范围与应用凭据

    当前产品连接使用https://ads.microsoft.com/msads.manage,它不是专用只读OAuth scope。只读由所选产品操作及用户实际账户访问共同约束。应用还需要developer token,但这项凭据不会增加账户权限。不要向支持人员发送developer token或他人凭据。

  3. 沿产品现有正常流程完成连接

    在目标Portal组织的Connections中,沿产品提供的Microsoft流程完成平台要求的同意/MFA。返回同一组织后,确认连接和广告账户。旧ads.manage或bingads.manage不能替代官方msads.manage要求;不要为消除读取报错直接改应用注册或管理员角色。

  4. 使用精确日期并保留原结果

    对支持该参数的工具使用source_policy=warehouse_only读取已存数据。指定已结束的精确日期,保留来源报表时区和币种。Microsoft的ReportTimeZone影响Yesterday等相对日期;未指定时官方默认PacificTimeUSCanadaTijuana,但这不证明已有结果就是该时区。只有期间总数不能证明每天完整。用自己的官方导出核同账户、同设置。

Microsoft访问或报表失败时

分别核身份、API访问与数据覆盖

invalid_grant、同意或MFA失败

这是授权失败,不证明账户没有花费。先请支持人员识别安全错误类别,再决定是否重新连接。所需同意或MFA由有权账户持有人沿正常产品流程完成,不转发一次性授权码或refresh token。

连接成功,但账户访问被拒绝

分别检查customer/account选择、用户实际账户角色、产品内权限与应用developer token配置。developer token不等于账户授权。保留该账户失败状态,不借管理员身份、不自动扩权。

只有期间总数,或末日缺失

保持partial及来源真实日期,不把期间总数平均拆成虚构日行,也不把缺失日期补零。请支持人员核原已存覆盖及报表设置;连接成功不是采集完成回执。

通过约定私密渠道提供时间及时区、客户端版本、原任务引用和安全错误码。不要发送密码、developer token、OAuth token、一次性授权码、API key、Authorization请求头或原始导出。

产品断开、平台撤销同意和已存报告处置分别核实。重新打开报告不会续上已撤销授权;处置申请要跟踪实际结果,不能把已提交当已完成。

Microsoft官方说明

来源核对日期:

返回首次只读任务

五个可直接使用的只读任务

首次账户读取之后,按实际需要选择任务。以下是请求示例,不表示某平台、宿主或完整自动巡检已通过验收。只使用所选工具真实支持的输入及约定账户范围。

核ROAS,不把转化价值写成收入

开始前准备

一个获准平台/账户、已结束日期、来源时区/币种、平台转化事件与归因设置,以及有权使用的官方对照。购买价值、全部转化价值和店铺收入分别保留。

请求示例
只读我已选且获准的这个账户及约定的已结束日期,对支持该参数的工具使用source_policy=warehouse_only。列花费、主要转化价值、ROAS定义、源字段、归因及覆盖;不拿全部转化价值替换。平台ROAS与店铺收入、利润、因果增量分开。解释同范围官方导出的差异,不改广告。

应取得的可用结果

逐账户保留源字段标签、币种和日期;仅在两数可得且花费非零时计算conversion_value / spend,并逐日列对照与差异。内部字段名revenue可能指平台转化价值,不等于实际回款;Meta购买别名不重复相加。

何时保持partial

事件、归因、币种、来源自然日或分母缺失时保持未知。花费为零,比率不可用,不写零ROAS。跨平台转化可能重叠;相加转化数或平均账户ROAS,都不能证明去重后的业务回报。

返回任务选择

只读核多个账户,不扩大访问范围

开始前准备

同一组织中明确获准的账户清单,逐个确认平台、连接和币种。先用已验账户,再按约定范围增加下一个。

请求示例
仅核这个组织中我明确选择且获准的账户,对支持的工具使用warehouse_only。逐账户列平台、来源时区/币种、覆盖日期、可用指标及安全失败状态;被拒绝和缺失分别保留。不发现其他组织、不新采集、不改权限。工具没有已验批量入口时,逐账户读取。

应取得的可用结果

汇总前先交付每个获准账户的独立结果,包括失败和缺失日期;不同币种分组,未知币种不猜。相同账户的重复连接不算额外业务表现。

何时保持partial

被排除或被拒绝的账户仍留在请求清单中,不能消失或变成零花费。部分账户不是全客户报告;不能借经理账户的更宽可见性读另一个tenant,也不在没有约定汇率方法与证据时跨币种合计。

返回任务选择

分享前先核工作区与接收人

开始前准备

自己的已登录组织、目标操作者、获准账户及原报告;分享前明确谁可接收。邮箱或显示名相似,不证明资产属于同一组织。

请求示例
读取前沿正常产品上下文确认当前组织与所选获准账户,只打开当前身份可见的原报告。访问被拒绝就返回安全错误并停止,不换tenant、不冒充actor、不扩role、不另建替代工作区。保存或分享报告前先解释具体操作。

应取得的可用结果

取得目标组织自己的报告,或明确访问拒绝。分享仅走真实支持且获准的路径,先核接收人和数据范围;当前身份能读,不证明另一个用户或组织也能打开。

何时保持partial

拒绝不是借管理员key的理由。归属或接收人权限不清时,先保持私密,沿约定渠道请有权负责人核实。截图和下载文件有各自的数据处理边界。

返回任务选择

区分文字工具与交互App是否可用

开始前准备

本次真实客户端/使用端及版本;key仅填该客户端的私密远程MCP设置。工具发现、文字结果、交互App和下载分别核。

请求示例
在这个客户端先发现实际GravityAds工具,再只读约定的已存账户数据。交互App不可用时,显示文字结果,以及工具确实返回的既有报告链接或导出路径;保留原任务引用供再次打开。不外推其他客户端支持,不把凭据贴进对话。

应取得的可用结果

在已测使用端取得可读结果、原任务引用及真实返回的报告/导出路径。App若能渲染,指标及缺失标签应一致;文字成功不证明App、浏览器网络或下载均可用。

何时保持partial

连接、长结果、App或导出失败时保留原任务及安全错误,不暗中重建采集,也不假定ChatGPT Web、WorkBuddy、豆包work表现相同;它们各自真实验收仍待完成。

返回任务选择

有真实基线,才做周度交接

开始前准备

一个获准账户、两个明确已结束且等长的期间,相同来源自然日、币种、归因和筛选。先用原报告,不重采;campaign级诊断需要对应细分证据,不能只靠账户总数。

请求示例
从原保存任务,使用支持的warehouse_only比较约定已结束期间与等口径基线。列当前值、基线值、双方覆盖、有意义的变化及缺口。不补日期,不在零或未知基线上算百分比,不从总数推因果,不创建定时任务。保留原报告,写保存补充前先解释。

应取得的可用结果

交接中包含同口径当前/基线数值、来源引用、覆盖和每个未解释差异的下一检查。观察到变化、诊断原因与建议广告动作分别记录;报告不等于广告修改批准。

何时保持partial

期间不完整、基线未知或缺细分时保持partial。不称完整自动巡检,不无证据解释原因,也不因请求中有“周度”就创建调度。

返回任务选择

可用已有合成报告练习核覆盖;它不是官方导出或客户案例。

打开已有合成示例

任务失败时保留原引用、时间及时区、客户端版本和安全错误码,通过约定私密支持渠道处理;不发送原始客户导出、密码、key、token或Authorization请求头。

按你的角色完成一次复核

先确定团队要做的决定和交接,再选择已有只读任务。以下流程不授予权限、不创建调度,也不修改广告。

品牌自投:先核清花费,再做决定

开始前准备

选定一个品牌、获准账户清单和复核人。记录已完整结束的账户自然日、来源时区与币种、转化定义,以及获准使用的官方导出。

  1. 先核访问范围

    读取前核组织和账户,先从一个账户开始。平台连接并不自动给每位同事全部账户的访问权。

    核对工作区边界
  2. 分开读取不同口径

    逐账户复核,区分购买价值、全部转化价值和店铺收入。按币种分组,不自行补汇率或合并ROAS。

    核对ROAS定义
  3. 把结论对回来源

    将报告的账户、日期、筛选条件和指标名称逐项对回官方导出。先列出差异和缺失行,再交复核人判断。

    查看合成对账示例
  4. 交接决定,不执行广告变更

    保留原任务和报告引用、核对来源、未解决差异及决定负责人。报告提出下一步,不等于已批准预算或广告变更。

    准备有基线的交接

交接什么

逐账户逐日表、来源定义与官方导出引用、差异清单、原任务/报告引用,以及负责下一步决定的复核人。

何时保持未完成

缺少同意、数据覆盖或转化定义时保持partial。平台归因转化价值不当利润,报告本身也不证明业务效果。

返回角色流程

代理商/代运营:逐客户保留独立证据

开始前准备

明确获准客户组织、账户及排除项,约定谁读取、谁复核、谁接收。每个客户沿自己的获准连接与报告上下文执行。

  1. 首读前核客户归属

    确认当前客户的精确组织、账户和操作者。不切到别的租户,不复用其他客户的key,也不凭相同品牌名推断权限。

    核对组织隔离
  2. 沿明确的账户清单逐项读取

    逐个读取获准账户。拒绝、断开和未完成的账户都留在清单中并注明状态,不通过静默剔除制造完整组合报告。

    使用多账户只读任务
  3. 形成客户独立交付包

    客户数据、日期、币种及原任务/报告引用分开保存。交付前核接收人,排除凭据及其他客户信息。

    核对报告证据结构
  4. 沿原任务恢复并交接

    结果不全时保留原任务引用与缺口原因,明确下一负责人和来源更新时间,不另造任务或声称已取得完整新报告。

    保留原报告身份

交接什么

逐客户独立交付包,包含纳入/排除账户清单、逐字段差异、未解决项、原始引用和接收人核对。

何时保持未完成

客户归属或许可不清就停。合同、平台登录或列表可见,本身都不代表可用于新客户或新接收人。

返回角色流程

多平台团队:先统一定义,再做周度交接

开始前准备

每个来源指定平台负责人,并指定一名报告复核人。合并观察前,先约定窗口、账户自然日时区、币种、转化事件、归因窗口和比较基线。

  1. 先形成来源范围表

    逐平台/账户记录各自时区、币种、数据新鲜度和转化名称。一个来源的完整日期,在另一个来源可能还没结束;不直接重标逐日数据时区。

    选择已有只读任务
  2. 渠道观察不当业务总额

    平台归因转化按来源保留。同一订单可能被多个平台记功,相加不等于去重收入或增量效果。

    分清归因和币种
  3. 核实际宿主表面

    在目标客户端分别核文字结果与交互App。App不可用时保留已支持的文字结果并记录交互缺口,不据此宣称所有宿主一致。

    核对宿主与App差异
  4. 带负责人和未结项完成交接

    按同一定义比较完整窗口。零基线和未知基线分开,逐项指定负责人并保留原报告引用。周度交接不自动创建定时任务。

    形成周度对照

交接什么

逐来源范围表和结果、可比/不可比字段、重复归因风险、已知缺口、原引用,以及每个未结项的下一负责人。

何时保持未完成

缺少汇率、去重或更细粒度来源证据时,不发布合并ROAS或重标时区后的逐日总额。未支持的平台/宿主组合保持待验。

返回角色流程

先选工作流,再比较证据

表格、报表看板和MCP对话分别解决不同环节。先确定需要交付的结果,再用同一个获准只读任务做对照。

这是工作流选型指南和带日期的公开产品资料核对,不是同账号实测、排名,也不宣称GravityAds效果更好。

你需要解决哪个环节?

平台后台与官方导出

以平台自己的筛选条件和导出作为逐字段核对基线,保留账户、日期、时区、币种及转化名称。

平台归因结果不等于独立验证的业务收入或增量效果。

表格或BI/报表工作流

需要可重复表格、明确公式或可复核看板时使用,同时保留来源引用和转换规则。

图表做得好,不代表连接新鲜度、缺失行、归因差异或客户权限已解决,这些要分别核。

MCP对话与报告复核

复核人需要在AI客户端提问时,使用已认证的工具连接,核实际工具、账户范围、返回字段和来源窗口。

MCP是连接协议,不证明某个宿主App界面、数据覆盖、只读约束或完整自动巡检已经可用。

优化与定时运营

需求涉及规则执行、定时监测或广告变更建议时,另做对应评估,核模式、审批和实际产品表面。

首次报表对照保持只读。工具能写、能审批或能调度,不代表已获准对你的账户执行这些动作。

厂商公开资料怎么说

核对日期为2026-10-20。以下是特定产品表面的厂商说法,不是独立安全或效果测试。按英文名称排序,不在这里认证报价、支付、当前套餐资格或实际运行表现。

官方来源 ·

Adspirer

其7月14日产品公告区分监测、提案审批和可选自动应用,属于不同运行模式。

你的评估中还要核什么: 记录所选模式;共同报表任务关闭广告变更,不把所有agent模式都当只读。

AgencyAnalytics

其MCP页面描述按客户限定范围查询已连接报表数据,并另有看板和报告交付表面。

你的评估中还要核什么: 核MCP实际可访问的客户及字段,再单独验要交接的报告或看板。

Markifact

其集成目录同时列出报表读取和写操作,包括工作流与agent中的变更。

你的评估中还要核什么: 核所选表面实际暴露哪些操作与审批设置;读测试不能证明全部写路径。

Optmyzr

其MCP变更指南描述暂存change request和人工复核,并说明当前policy guardrail是可明确批准越过的警告,不是无条件硬阻断。

你的评估中还要核什么: 报表读取和变更申请分开验;核复核人的Apply权限和套餐资格,不把警告当硬权限边界。

Pipeboard

其Meta Ads token指南描述只读、按工具和按账户控制;文档将权限限定token列为Pro+,账户限定列为Agency。

你的评估中还要核什么: 核当前套餐、所选token及账户,不外推全部token或其他平台都有同样限制。

TrueClicks

其MCP指南描述对已连接Google、Microsoft和Meta Ads的只读访问,并可按客户标签限定connector范围。

你的评估中还要核什么: 核connector资格和key的实际账户范围;产品UI的操作能力与文档所述只读MCP是不同表面。

怎样做同条件只读对照

  1. 只评估已有许可的账户和工具,记录产品、套餐、表面及观察日期。凭据与客户身份不进入公开记录。
  2. 固定同一账户、来源时区、币种、筛选、归因及转化定义。比较完整七天和前七天,各产品在同一24小时内读取。
  3. 保留官方后台/导出基线。共同字段、缺失字段和不可比字段分开记录;约定任务之外不可用的功能不记零分。
  4. 首轮授权、同步等待与数据就绪后的任务时间分开计,失败、人工辅助、复核和修正工时也计入,不只取最后成功回复。
  5. 核账户边界、逐字段差异、原任务恢复和复核人可使用的交付物。只读对照不执行广告写操作。
  6. 取得真实获准观察后才发布结论。不凭产品文档、合成示例或私有加权总分制造赢家。

测试前先约定共同任务

账户周度复核
固定完整日期、campaign范围、花费及约定转化字段,保留官方字段差异和缺失日期。
多账户异常
沿逐个获准的明确账户清单读取,保留拒绝和未完成状态,不混币种。
Google搜索词复核
必须有实际可用、筛选和覆盖相同的搜索词报告;指标汇总不能代替缺失搜索词行。
Meta素材复核
先确认素材级来源字段和比较日期实际可用;campaign总额不能证明素材疲劳或因果效果。

空白对照记录

仅在实际获准观察后填写。Null表示未知,这份空白表不是测试结果。工作记录保密,公开只使用获准、去标识的证据。

{
  "schema": "gravityads.readonly_evaluation.v1",
  "status": "not_run",
  "consentConfirmed": false,
  "scope": {
    "organizationAlias": null,
    "platform": null,
    "accountAlias": null,
    "sourceTimezone": null,
    "currency": null,
    "currentWindow": null,
    "previousWindow": null,
    "conversionDefinition": null,
    "attributionWindow": null
  },
  "product": {
    "name": null,
    "plan": null,
    "surface": null,
    "versionOrObservedDate": null,
    "readOnlyModeVerified": false
  },
  "execution": {
    "task": null,
    "startedAt": null,
    "finishedAt": null,
    "firstAuthorizationMinutes": null,
    "syncWaitMinutes": null,
    "dataReadyTaskMinutes": null,
    "manualReviewMinutes": null,
    "assistanceOrFailure": null
  },
  "evidence": {
    "officialExportReference": null,
    "taskReference": null,
    "reportReference": null,
    "fieldDifferences": null,
    "missingFields": null,
    "incomparableFields": null,
    "recoveryObservation": null
  },
  "result": null
}
返回只读任务

复核前可以核对的事实

每条回答都附适用范围和来源。产品文档、厂商说法与实际账户结果是不同证据;核对日期不代表全部平台、套餐或宿主都已可用。

GravityAds初期辅助只读范围是什么?

在本次体验已确认的组织、账户、平台和客户端范围内,读取已结束报告日期的账户指标,并回到原保存工作。

适用范围: 一次指标读取不证明完整自动巡检、广告写入审批或全平台可用。

核对日期:

缺数据就表示零花费或零ROAS吗?

不是。缺失日期或分母保留未知,有记录日期的小计不当完整期间总计。

适用范围: 公开对账算例是合成数据,用来说明核对方法,不是客户效果。

核对日期:

只读仓库复核时缺数据怎么办?

所选工具支持source_policy=warehouse_only时使用该设置,缺覆盖就报告缺口,不静默请求实时广告数据。

适用范围: 提示词本身不能缩减凭据权限,实际工具、运行环境和账户范围仍须执行获准边界。

核对日期:

能重标账户自然日或相加平台ROAS吗?

保留来源日期、时区、币种和归因定义。没有合适的细粒度来源,不能将逐日桶直接移到另一个时区。

适用范围: 不同币种和重叠的平台归因转化需要明确对账,不是去重后的业务总额。

核对日期:

MCP工具成功就证明所有客户端App都可用吗?

不是。文字结果与目标交互App分别核;当前只有受支持文字表面时,保留文字结果。

适用范围: 协议或SDK检查不认证ChatGPT Web、WorkBuddy、豆包work或其他真实客户端体验。

核对日期:

readOnlyHint是权限边界吗?

MCP维护方将工具annotation定义为提示,不是强制约束。服务器的声明不能代替实际权限和行为核对。

适用范围: 这是协议事实,不是对GravityAds或其他厂商的独立安全认证。

核对日期:

返回工作流选型

Quick Start

Connect GravityAds to your AI workflow in under 5 minutes. You'll need an API key from your GravityAds MCP workspace.

1. Get your API key

Sign in to GravityAds MCP → AI Connection → Create new key. The raw key is shown once — copy it immediately.

2. Configure your MCP client

Add GravityAds as an MCP server in your client configuration:

json
{
  "mcpServers": {
    "gravityads": {
      "url": "https://mcp.gravityads.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

3. Start using tools

Ask your AI assistant to use GravityAds tools:

text
"Show me my Google Ads campaign performance for the last 7 days"
"Compare my Meta Ads CPC against industry benchmarks"
"Generate a daily brief for all connected accounts"

MCP Tools Reference

GravityAds exposes MCP tools for reading ad data, generating insights, and managing controlled actions across platforms.

Read-Only Intelligence

decision_contextUnified decision context across connected accounts
customer_metric_summaryCustomer-level metric aggregation
optimizer_daily_briefAI-generated daily optimization brief
optimizer_weekly_planWeekly optimization plan with priorities
benchmark_compareIndustry benchmark comparison
candidate_searchFind optimization candidates
candidate_explainDeep-dive explanation of a candidate
data_freshness_checkCheck ETL freshness for each account

Controlled Actions (Phase 2)

controlled_draftDraft an optimization change
candidate_preflightValidate a candidate before drafting
controlled_action_approveApprove a drafted action
controlled_action_executeExecute an approved action
controlled_action_observeObserve results of an executed action

Account Management

business_contextManage business context metadata
workbench_contextWorkbench overview for a tenant
market_signal_snapshotMarket signals for connected accounts

REST API

In addition to MCP, GravityAds exposes a full REST API. The OpenAPI schema is the single source of truth.

OpenAPI Schema

bash
curl https://api.gravityads.dev/openapi.json | jq .

Authentication

All API requests require authentication via either:

  • API Key — via Authorization: Bearer <key> or X-GravityAds-API-Key header
  • JWT (OIDC) — verified via JWKS with issuer/audience validation

Example: Get tenant readiness

bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.gravityads.dev/tenant/readiness | jq .