G
GravityAds
AI Agent Ad Intelligence

GravityAds Ads MCP / API

Ad intelligence for AI agents, ad teams, and agencies. Query, audit, and execute controlled ad workflows.

Controlled Operation Workflow

Analyze

AI agent reads ad data

Recommend

Generate optimization recommendations

Review

Human reviews draft changes

Approve

Team member approves execution

Execute

Controlled execution of changes

Who Is It For

Built for ad teams, not just developers

Ad Optimizers

Query cross-platform ad performance through AI agents. Get campaign-level insights without writing queries.

  • Natural language ad queries
  • Campaign performance summaries
  • Budget allocation suggestions

Built for ad teams, not just developers

AI agents make API-level workflows accessible to ad ops, agency managers, and growth leads.

Controlled operations

Connect data, approvals, and tool access through safe, auditable workflows.

Portal stays technical

API keys, docs, MCP setup, and console workflows remain at portal.gravityads.dev.

Start with one read-only account

Review completed reporting dates, inspect missing data, and return to saved work. No advertising changes are part of this first session.

  1. Confirm the authorized operator, account, client, trial terms, data handling and support contact before connecting real data.
  2. Sign in to your own organization in Portal. Use the agreed product connection and account selection, then your client's native remote-MCP settings.
  3. Discover the client's actual tools. Read the agreed account and dates with gravityads.metrics.summary and source_policy=warehouse_only. Missing saved data stays missing; it does not trigger a live collection.

Text tools and interactive App UI are accepted separately. A prompt does not reduce a credential's permissions. Keep keys in the client's private settings, not in shared files or screenshots.

First read

Read only my selected authorized account for the agreed completed dates, using source_policy=warehouse_only. Show the source-account timezone, currency, covered and missing dates, then the available metrics. Do not call advertising APIs, create schedules, change ads or fill missing values. Explain any proposed collection or saved-task write before proceeding.
Configuration and request examples

Placeholders only. Replace the account and dates with the agreed scope. Do not inject another tenant or 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"
  }
}
Download the guide and examples

English and Chinese · ZIP

A missing day is not zero spend

Synthetic example, not a customer case or an official platform export.

Two of three dates are covered. Source calendar: Asia/Hong_Kong. Currency: USD. No UTC re-bucketing.

Synthetic spend example: $40 and $60 observed on two dates, with no data for the third date. The third date is not shown as zero.
Synthetic example, not a customer case or an official platform export.
DateIllustrative referenceObserved spendObserved clicks
2026-01-01$40$4020
2026-01-02$60$6030
2026-01-03$50MissingMissing

Covered-date subtotal: $100 and 50 clicks across two days. The actual three-day totals remain unknown; full-period reconciliation is blocked.

Check a report before acting on it

Read the full guide

The worked example is synthetic, not a customer case or a claim of improved advertising results.

A report can contain correct numbers and still answer the wrong question. Two days of accurate spend do not make a complete three-day report. An account's local reporting day is not necessarily a UTC day. A platform's conversion value is not automatically the profit received by a shop.

Before acting on an AI-generated ad report, check its scope, coverage and comparison source. The goal is a result you can explain and return to, not simply a plausible recommendation.

Start With the Reporting Question

Name the account, platform, completed date range and currency. Keep the source account's reporting timezone and the platform's attribution and filter settings with the result. An AI assistant should tell you when those settings are unknown rather than silently supply defaults that make two reports appear comparable.

Use a narrow first task: read one authorized account for completed dates, show the available metrics and explain missing information. Reading a report does not authorize a change to ads, budgets or delivery status. Creating a saved task is also different from changing an ad; the assistant should explain any state it will save.

Separate a Subtotal From a Complete Period

Consider a synthetic account reporting in USD on Asia/Hong_Kong calendar days. The requested period is 1–3 January. A reference table has $40 on the first day, $60 on the second and $50 on the third. The observed report has the first two days but no record for the third.

The report can truthfully say that its two covered dates contain $100. It cannot call that the complete three-day total. It cannot turn the missing day into $0 or infer that the account stopped spending. The reference's $150 and the observed $100 subtotal are not interchangeable full-period measures.

This distinction matters before computing change percentages, CPA or ROAS. A missing date or denominator can produce an attractive-looking ratio without supporting the requested conclusion. Keep the missing value visible, label the coverage partial, and identify the next check. The accompanying synthetic sample shows the exact rows rather than hiding the gap inside a summary.

Use an Independent Comparison

Compare the result against the advertising platform's own export or UI for the same account and reporting definition. Align dates, timezone, currency, attribution and filters before comparing each agreed metric. Record differences, missing values and the tolerance used. A total that matches does not prove every daily row matches.

Reading the same warehouse through a second screen is useful for checking display consistency, but it is not an independent platform reconciliation. Similarly, a small on-screen preview does not establish that the full underlying result was retrieved. Long evidence should be inspected through the original result's pagination or export path.

Platform conversion value should retain its source label. Calling it shop revenue, cash received or profit requires additional evidence. Do not combine currencies or relabel local reporting days as UTC merely to simplify a chart.

Preserve the Original Result

When a response is interrupted, return to the same saved task and report. Check its existing status and evidence before starting anything again. Recreating the task can make it harder to distinguish an original result from a new collection or a duplicated operation.

For an explicitly warehouse-only review, use source_policy=warehouse_only when the selected tool exposes it. If the data is missing, report the gap rather than silently falling back to a live advertising query. Any new collection needs its own clear account scope and disclosed operation. An assistant's text request does not expand account permissions.

Know What Stopping Means

Product disconnect, provider-side authorization revocation and stored-data disposition are separate checks. Ask which new reads and collection paths are stopped, what remains stored, and how a disposition request is tracked. A submitted request is not a completed deletion receipt.

A practical first session ends with an understandable result: what was verified, what remains missing, how to reopen the original report and how to stop access. Only then should another genuinely useful task test whether the workflow is worth using again.

GravityAds MCP's initial assisted scope follows this approach: account metrics for completed reporting dates and return to saved work. The supported platform, client and data scope must be confirmed for the session. Text tools and interactive App UI are separate capabilities; a successful SDK call does not prove every client renders the App. Full automated audits, advertising changes and profit attribution should not be inferred from the initial read-only session.

Download the article

Return to the original saved task and report without creating another task or recollecting. Product disconnect, provider revocation and stored-data disposition are separate steps; a submitted request is not completed deletion.

For help, share the time, client/version, original task reference and safe error code through your agreed support contact. Do not send passwords, keys, Authorization headers or raw customer exports.

Ready to let AI agents manage your ads?

Also see: True ROAS, real ad profit analytics for Shopify