MCP Reference
Operate your Google Ads accounts from Claude Code, Codex, or claude.ai — the same read and propose tools the dashboard uses, over MCP.
AI Google Ads has no REST API. Its external developer surface is a remote MCP server at /api/mcp that
exposes the Ads copilot's tools — every read and every gads_propose_* write — to any MCP client. An agent in
Claude Code operates an account exactly as the dashboard does, behind the same
safe-apply policy.
Token scopes
Org-scoped vs project-scoped, read vs write.
Connect Claude Code
Add the server with a token, or install the plugin.
Connect claude.ai
Add a custom connector via OAuth.
Set up over MCP
Connect and import an account without leaving your client.
The endpoint
| URL | <your-app-origin>/api/mcp |
| Transport | Streamable HTTP |
| Auth | Authorization: Bearer <token> — a minted gads_… token or a claude.ai OAuth JWT |
The result envelope
Every tool returns a JSON object. Success is { "ok": true, … }; failure is
{ "ok": false, "error": "…" }. Read the error — it usually tells you the next step (connect the account,
trigger a sync, pass a projectId).
Reads are safe, writes move money
Read tools (gads_list_*, gads_get_*, gads_run_gaql_query, …) never change the account. Write tools are all
named gads_propose_* and are money-moving: each is dry-run validated, then auto-applied or queued by the
policy. A read-scope token can't call them.
Tool categories
| Category | Tools | What they do |
|---|---|---|
| Reads | 23 | Performance, inventory, plan, change history, audit, GAQL. |
| Setup & connection | 9 | Connect, discover, import, sync, targets. |
| Writes | 34 | Every money-moving gads_propose_* change. |
| Approvals | 3 | Approve, reject, revert (MCP-only). |
| Keyword expansion | 2 | Silo discovery and ideation. |
| Free audit | 3 | Generate and share a client-ready report. |
| Projects | 2 | List accounts, update the brief. |
| Skills & web | 3 | Load a playbook, fetch a URL, read an attachment. |
The MCP server also ships always-on instructions at connect time and, for clients that install the plugin,
runtime playbooks — so a fresh client already knows the golden paths without reading these pages.