Documentation

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

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.

Google Ads access: what read-only means

A successful Google sign-in is only one step. Check the Google Ads account role, the app's platform eligibility, the product's account permissions and the data available for your task separately.

Google account role and OAuth consent

Google Ads uses the same OAuth scopes for read-only and read-write operations; its account roles determine the user's access. The adwords scope is not a dedicated read-only scope. A read-only instruction in a chat does not narrow that grant. Authorize only your own permitted account through the agreed product flow, and review what the Google consent screen requests.

App eligibility is a separate check

Google Ads API access eligibility and OAuth app publishing or verification status are different checks. One does not prove the other, and this guide does not certify the current status of a particular connection. Use the actual connection result and the team's agreed access scope.

Product identity and account permissions

Your Portal organization, operator, selected connection and permitted advertising account must match. Discovering an account is not a grant to read it. A platform login does not give another organization access, and an operator's cloud login is not your Google Ads product authorization. Never borrow a colleague's account or share a token to bypass a denial.

Saved data and live collection

source_policy=warehouse_only reads existing persisted data; it does not collect a newly connected account. An empty or partial result can mean that the agreed dates are not available yet. Keep the source-account reporting timezone and currency, and arrange any new collection separately before comparing with an official Google Ads export.

When a connection or read fails

Check the failure before reconnecting

An access or permission denial

Confirm the selected organization, account and connection with the authorized owner. Ask support to distinguish product permission from Google account access and app eligibility. Do not widen a role, scope or account list merely to clear the error.

invalid_grant or a rejected refresh

The authorization cannot currently be renewed. The error alone does not identify the cause. Google lists revocation, expiration and token limits among possible reasons; an external OAuth app in Testing also has a seven-day refresh-token rule, except for the documented basic identity-scope cases. Do not infer that your connection is in Testing from this error. Have support identify the safe failure category first; reconnect only through the normal product flow when the permitted account holder is available.

A successful connection with missing metrics

Check the completed reporting dates, source calendar, selected account and saved-data coverage. A connection success is not a collection receipt or proof that every date exists. Missing rows stay missing, not zero, and do not trigger a hidden live query.

Send support the time and timezone, client/version, original task reference and safe error code through the agreed private channel. Do not send passwords, authorization codes, access or refresh tokens, API keys, Authorization headers or raw customer exports.

Product disconnect stops access only along the paths actually covered by that operation. Provider-side revocation and stored-data disposition are separate checks. Reopening a saved report does not renew a revoked connection, and submitting a disposition request is not proof that stored copies have been removed.

Google documentation

Sources checked:

Return to the first read-only task

Connect Meta Ads for a read-only review

Start with one permitted ad account and completed reporting dates. Signing in to Portal with Google or GitHub is not Meta advertising consent. This guide describes the read-only path, not certification that your connection or our app currently qualifies for every account.

  1. Confirm the account and the person authorizing it

    In your own Ads Manager, identify the intended ad account and confirm you can access it. In Portal, check the selected organization before opening Connections. A business portfolio, Page or Instagram identity is not the advertising account itself. Use only assets the owner has authorized for this review.

  2. Review the actual consent

    The product's Meta read-only connector requests ads_read; advertising changes use a separate ads_management path. Meta distinguishes Standard and Advanced Access, including access to other people's accounts. An account role, granted permission and app access level are separate requirements. Do not add ads_management or send a system-user token to support just to make a read work.

  3. Connect through the product, then confirm the selection

    Use the normal Meta connection flow available in your organization. Review the provider's requested access and return to the original Portal organization. Confirm the selected connection and permitted ad account before reading. An account in discovery is not a product grant; a successful connection is not proof that reporting data has arrived.

  4. Read and reconcile one complete period

    For a saved-data-only task, use source_policy=warehouse_only where the tool exposes it. Keep the source timezone, currency, purchase event, attribution window and reporting-time basis with the result. Meta's Insights schema exposes purchase-related values separately; do not add overlapping purchase aliases. Compare the same definitions with your own Ads Manager export before treating the report as checked.

If Meta access or reporting fails

Find the failed step

Consent returns, but the account is absent or denied

Recheck the original organization, connection and ad account with its authorized owner. Support should distinguish product permission, asset access and app eligibility. Do not create another workspace, borrow an identity or broaden permissions to bypass the denial.

Authorization expired, was revoked or cannot be renewed

Keep the safe error code and original task reference. Have support identify the failure category; reconnect only through the normal product flow when the permitted person can act. Do not paste tokens into chat or repeatedly reconnect without a changed condition. No fixed token lifetime is promised here.

The read succeeds, but dates or ROAS are missing

Check account selection, saved coverage and the original conversion definition before any new collection. Missing purchase value is not zero revenue. A subtotal for covered dates is not a complete-period total, and warehouse_only must not silently become a live advertising request.

Use the agreed private support channel for the timestamp/timezone, client version, original task reference and safe error code. Never send passwords, authorization codes, access or refresh tokens, API keys, Authorization headers or raw customer exports.

Product disconnect, provider revocation and stored-data disposition are separate operations. Confirm which new reads and collection paths stop; a submitted disposition request does not prove every stored or downloaded copy has been removed.

Meta sources

Sources checked:

Return to the first read-only task

Connect Microsoft Advertising for a read-only review

Microsoft Advertising may be labelled Microsoft or Bing in a tool. Confirm the platform and account, not just its display name. Portal sign-in, advertising consent, API eligibility and saved reporting coverage are separate checks.

  1. Keep customer, account and organization distinct

    In your own Microsoft Advertising account, confirm the customer and account identifiers. The account number shown in the interface is not the API account ID. In Portal, verify the organization and permitted account selected for this review; seeing an account does not grant another organization access.

  2. Understand the consent and app credential

    The current product connector uses https://ads.microsoft.com/msads.manage, not a dedicated read-only OAuth scope. Read-only is enforced by the selected product operations and the user's actual account access. The app also needs a developer token; that credential does not add account permissions. Never send a developer token or another person's credentials to support.

  3. Complete the available normal connection flow

    From Connections in the intended Portal organization, follow the Microsoft flow offered by the product and complete the provider's required consent/MFA. Review the result back in the same organization, then confirm the connection and account. Old ads.manage or bingads.manage consent is not a replacement for the documented msads.manage requirement. Do not change an application registration or administrator role just to clear a read error.

  4. Use exact dates, coverage and the original result

    Read saved data with source_policy=warehouse_only where exposed. Use explicit completed dates and retain the source reporting timezone and currency. Microsoft's ReportTimeZone controls how relative dates such as Yesterday are resolved; its documented default is PacificTimeUSCanadaTijuana when omitted. This does not prove the timezone of an existing result. Period totals alone do not establish daily coverage. Reconcile the same account and settings with your own official export.

If Microsoft access or reporting fails

Check identity, API access and coverage separately

invalid_grant, consent or MFA failure

This is an authorization failure, not proof that an account has no spend. Ask support for the safe failure category before reconnecting. The authorized account holder completes any required consent or MFA through the normal product flow; do not share authorization codes or refresh tokens.

Connection succeeds, but account access is denied

Check the customer/account selection, the user's actual account role, product permission and app developer-token configuration separately. A developer token is not an account grant. Leave the failed account excluded; do not borrow an administrator identity or increase permissions automatically.

Only a period total is available, or the last date is missing

Keep the result partial and retain the source's actual dates. Do not divide a period total into invented daily rows or backfill missing days with zero. Ask support to check the original saved-data coverage and reporting settings; a successful connection is not a completed collection receipt.

Send the timestamp/timezone, client version, original task reference and safe error code through the agreed private channel. Do not send passwords, developer tokens, OAuth tokens, authorization codes, API keys, Authorization headers or raw exports.

Disconnecting the product, revoking provider consent and disposing of retained reports are separate checks. Reopening a saved report does not renew revoked authorization. Track any disposition request to its actual result rather than treating submission as completion.

Microsoft documentation

Sources checked:

Return to the first read-only task

Five useful read-only tasks

Choose the task you need after the first account read. These are request examples, not evidence that a platform, client or automated audit has passed acceptance. Use only the selected tool's actual inputs and your agreed account scope.

Check ROAS without inventing revenue

Before you start

One authorized platform/account, completed dates, source timezone/currency, the platform's conversion event and attribution settings, and an official comparison you are allowed to use. Keep purchase value distinct from all-conversion value and store revenue.

Request example
Using only the selected authorized account and agreed completed dates, read saved data with source_policy=warehouse_only where supported. Show spend, primary conversion value, ROAS definition, source fields, attribution and coverage. Do not substitute all-conversion value. Keep platform ROAS separate from shop revenue, profit and causal lift. Explain differences from the same-scope official export without making advertising changes.

What a usable result includes

A per-account result with the original source labels, currency and dates; conversion_value / spend only when both values exist and spend is nonzero; a daily comparison and a list of differences. The internal label revenue can mean platform conversion value, not cash received. Meta purchase aliases must not be added together.

When to keep it partial

Unknown event, attribution, currency, source day or missing denominator stays unknown. Zero spend makes the ratio unavailable, not zero ROAS. Cross-platform conversion totals can overlap; neither summing conversions nor averaging account ROAS establishes a deduplicated business return.

Back to task choices

Review several accounts without widening access

Before you start

An explicit permitted account list in one organization. Confirm each platform, connection and currency separately. Start with the already accepted account before adding another one to the agreed scope.

Request example
Review only my explicitly selected permitted accounts in this organization. Use warehouse_only where supported. For each account show its platform, source timezone/currency, covered dates, available metrics and safe failure status. Keep denied or missing accounts separate. Do not discover other organizations, collect new data or change permissions. Use individual reads if this tool does not expose a verified batch operation.

What a usable result includes

One identifiable result per permitted account, including failures and missing dates, before any summary. Currency groups stay separate and unknown currency is not guessed. Duplicate connections to the same account are not counted as additional business performance.

When to keep it partial

An excluded or denied account does not disappear from the requested-account checklist or become zero spend. A partial list is not an all-client report. Do not use a manager's wider visibility to read another tenant, and do not use cross-currency totals without an explicitly agreed, evidenced FX method.

Back to task choices

Check the workspace before sharing a result

Before you start

Your own signed-in organization, the intended operator, permitted account and original report. Agree who may receive the result before sharing; a similar email address or display name is not proof of shared ownership.

Request example
Before reading, confirm the current organization and selected permitted account through the normal product context. Open only the original report available to this identity. If access is refused, return the safe error and stop. Do not switch tenants, impersonate another actor, broaden a role or create a replacement workspace. Explain any report save or share operation before performing it.

What a usable result includes

The intended organization's own report or an explicit access refusal. Share only through an actually supported and permitted path, with the recipient and data scope checked. A normal read does not prove that a different user or organization can open it.

When to keep it partial

A denied request is not a reason to borrow an administrator key. If ownership or the permitted recipient is unclear, keep the report private and ask the authorized owner via the agreed channel. A screenshot or downloaded file has its own handling boundary.

Back to task choices

Tell a text-tool result from an interactive App

Before you start

The actual client/surface and version you intend to use. Put the key only in that client's private remote-MCP settings. Tool discovery, text output, interactive App rendering and downloading are separate checks.

Request example
In this client, discover the available GravityAds tools and read only the agreed saved account data. If an interactive App is unavailable, show the text result and the existing permitted report link or export path if actually returned. Keep the original task reference so I can reopen it. Do not claim a different client is supported or paste credentials into the conversation.

What a usable result includes

A readable result in the tested surface, its task reference and any actual report/export path. An App that renders should preserve the same metric values and missing-data labels. Text success alone does not prove App, browser-network or download support.

When to keep it partial

If the connection, long result, App or export fails, retain the original task and safe error. Do not silently create a new collection or assume ChatGPT Web, WorkBuddy and Doubao work behave the same. Their separate real-client acceptance remains pending.

Back to task choices

Prepare a weekly handoff with a real baseline

Before you start

One permitted account, two explicit completed periods of equal length and the same source calendar, currency, attribution and filters. Use the existing report first rather than recollecting. Campaign-level diagnosis needs campaign-level evidence, not just an account total.

Request example
From the original saved task, compare the agreed completed period with its equally defined baseline using warehouse_only where supported. Show current and baseline values, each period's coverage, meaningful changes and unresolved gaps. Do not fill missing dates, calculate a percentage from a zero or unknown baseline, infer causes from totals or schedule new runs. Preserve the original report and explain any proposed saved follow-up before writing it.

What a usable result includes

A handoff containing the same-scope current/baseline figures, source references, coverage and the next check for each unexplained difference. Distinguish an observed change from a diagnosis or recommended ad action; a report is not approval to modify ads.

When to keep it partial

An incomplete period, unknown baseline or missing breakdown stays partial. Do not call the result a full automated audit, attribute the change to a cause without evidence or create a schedule merely because the request mentions weekly.

Back to task choices

Use the existing synthetic report to practise checking coverage; it is not an official export or a customer case.

Open the existing synthetic example

For a failed task, keep its original reference, time/timezone, client/version and safe error code. Use the agreed private support channel, not raw customer exports, passwords, keys, tokens or Authorization headers.

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 .