Google Ads

vTilt can manage your Google Ads account through the same MCP endpoint your AI client already uses for analytics. There is no second server to run: the google-ads-* tools are always listed in tools/list so your agent knows the capability exists. Calls succeed only after you connect an account in project settings (otherwise the server returns feature_disabled).

#Connect Google Ads (required first)

The tools are listed immediately, but return feature_disabled until a project has a connected Google Ads account.

1. Open Project → Settings → Google Ads.
2. Click Connect Google Ads and complete the Google consent screen. vTilt requests the https://www.googleapis.com/auth/adwords scope.
3. After the redirect, vTilt discovers the accounts you can access and lists them. Pick the default account the tools should use when a call doesn't name one.
4. If you manage accounts through an MCC (manager account), set the manager (login) customer id.

vTilt stores the OAuth refresh token encrypted at rest and holds the platform developer token server-side. Your AI client never sees or sends credentials — tool inputs accept neither a refresh token nor a user id.

To stop access, click Disconnect on the same page — vTilt deletes the stored token and linked accounts. The tools stay in tools/list for discoverability; calls return feature_disabled until you connect again.

After switch-project, check features.google_ads in the tool response (or call context-get). You can call google-ads-* tools as soon as that flag is true — re-run tools/list only if your MCP client caches the catalog and still omits other feature-gated tools (replay, AI memory).

#Permissions

Google Ads access is gated by a dedicated google_ads permission resource:

Write tools additionally require a write-scoped credential (an mcp:write OAuth scope or a personal API key with write access), and every write is recorded in the project audit log.

#Reading account data

Always learn the valid fields before querying — the tools steer you to do this so you never guess field names.

1. google-ads-resource-metadata-get — pass a resource (e.g. campaign, ad_group_ad, keyword_view) to get the selectable fields.
2. google-ads-search — assemble a read-only query from resource, fields, and optional conditions, order_by, limit. vTilt builds and validates the GAQL server-side.
3. google-ads-customers-list — see which accounts are linked to the project.

Every tool takes an optional customer_id (dashed 123-456-7890 or digits 1234567890 — both work). Omit it to use the project's default account.

A search for the last 30 days of campaign spend looks like:

{
  "resource": "campaign",
  "fields": [
    "campaign.id",
    "campaign.name",
    "metrics.cost_micros",
    "metrics.clicks"
  ],
  "conditions": [
    "campaign.status = 'ENABLED'",
    "segments.date DURING LAST_30_DAYS"
  ],
  "order_by": "metrics.cost_micros DESC",
  "limit": 25
}

#Managing the account (writes)

Write tools mutate the connected account. They cover the common workflows:

#Troubleshooting