Documentation

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

Quick Start

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

1. Get your API key

Sign in to the GravityAds Portal → API Keys → 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://api.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 .