Meta's official Ads AI Connectors shipped on April 29, 2026, and the headline for marketers is the setup: a single Meta Business OAuth click instead of a Developer App and days of App Review. This guide walks the whole thing — the MCP server, the CLI, scopes, the one gotcha that can spend real money, the rate-limit math — and then the part most guides skip: a tiered prompt library we actually run, and a 30-day rollout that won't get your account flagged.
New to why this matters? Start with What Meta's Official MCP Means for AI Ad Teams; this post is the how-to.
Before you start
You need (heyOz):
- A Meta Business Manager account with an admin role on the ad account (Business Settings → Accounts → Ad Accounts).
- An MCP-compatible client: Claude Desktop or Claude.ai, ChatGPT Plus+, or Cursor for the MCP server; Claude Code / Codex / CI for the CLI.
- Marketing API access — the free Development tier is enough to start.
Option A — the MCP server (conversational, ~5 minutes)
This is the path for analysis, reporting, and ad-hoc questions in chat. Where you add the connector depends on your client:
| Client | Where to add the connector |
|---|---|
| Claude Desktop | Settings → Connectors → Add custom connector |
| Claude.ai | Profile → Settings → Integrations → Add integration |
| ChatGPT Plus | Profile → Settings → Connectors → Add MCP server |
| Cursor / config-file | edit ~/.cursor/mcp.json |
Then five steps:
- Confirm Business access at business.facebook.com — admin on the ad accounts you want to use.
- Open your client's connector settings (see the table above).
- Add the official endpoint
https://mcp.facebook.com/adswith transport HTTP. - Authenticate via OAuth — complete the Meta Business login and pick your scope (read-only, read/write, or read/write/financial), granted per user, per account. Start read-only.
- Test it — ask
List all my active Meta ad accounts and the campaigns currently running.Accounts should appear within seconds.
Config-file clients (Cursor, etc.) use this entry:
{ "mcpServers": { "meta-ads": { "type": "http", "url": "https://mcp.facebook.com/ads" } } }Option B — the CLI (deterministic, ~10–15 minutes)
This is the path for scripted, repeatable, or bulk operations (Claude Code, Codex, CI) (adsuploader):
# Python 3.12+ required
pip install meta-ads # or: uv pip install meta-ads
meta ads whoami # confirm the connectionThe CLI authenticates through Meta Business OAuth as well, and is built as a defined sequence an AI assistant can work through — so Claude Code can run the install and auth for you. The rule of thumb: MCP for analysis, CLI for execution.
The one gotcha that can cost money
The two surfaces differ on a detail that matters: through the MCP, entities an agent creates land paused. Through the CLI, resources are created active by default — you must pass --status PAUSED explicitly in automated flows (adsuploader). Never let an unattended CLI job create campaigns without that flag, or you can ship live spend with no review.
Rate limits, in plain math
Development access is 60 score/hour — a read costs 1 point, a write costs 3. So a single "scan all my campaigns" prompt that pulls 40 entities burns ~40 of your 60 points; two of those in an hour and you're throttled. For real workloads, apply for Standard access (9,000 score/hour) through Business Suite (heyOz). The MCP also preloads ~55,000 tokens of tool descriptions per session, so high-volume daily use is cheaper on the CLI.
Our prompt library (write these yourself — don't copy a generic list)
Most setup guides hand you a flat list of prompts. The problem with that list is it produces data, not decisions, and the vague ones invite the model to invent confident numbers. These are the prompts we actually run, organized by the read → diagnose → act loop. Two rules baked into every one: pin the date range and breakdown, and keep writes gated.
Tier 1 — read-only triage (safe on day one):
- Watchlist, not advice:
Across all connected accounts, list campaigns from the last 7 days with [ROAS](/glossary/roas) below [target], frequency above 3.5, OR [CTR](/glossary/ctr) down more than 20% vs the prior 7 days. Sort by spend. Don't recommend changes — just the watchlist with the numbers. - Pacing check:
For each active campaign, compare yesterday's spend to its daily budget and its 7-day average. Flag anything pacing above 120% or below 60%, with the dollar variance. - Creative fatigue:
List ads where frequency is above 3 and CTR has declined for 3+ consecutive days in the last 14 days (use that exact window). Show the CTR trend per ad.
Tier 2 — diagnosis (still read-only, deeper):
- Signal hygiene:
Audit each dataset's event match quality over the last 30 days. Flag any Purchase or Lead event-volume drop above 15% week-over-week, and say whether it looks like a pixel or a CAPI problem. - Catalog health:
List catalogs with feed errors, and any items that are out-of-stock or disapproved but still have active ads pointing to them. - Benchmark gap:
Compare my CTR, [CPM](/glossary/cpm), and [CPA](/glossary/cpa) to Meta's industry benchmark for [vertical]. Show only the metrics where I'm materially worse, and the campaigns driving the gap. - Anomaly, explained from data only:
For any campaign with a day-over-day CPM spike above 30% in the last 7 days, pull the auction and delivery diagnostics and give the 2 most likely causes. Do not speculate beyond what the tools return.
Tier 3 — gated actions (writes, human-approved, created paused):
- Test, don't ship:
Draft (paused) a duplicate of [winning ad set] with budget capped at [X] for audience [Y]. Show me the diff before you create it, and do not activate anything. - Reallocation as a proposal:
Propose a budget reallocation across [campaigns] that holds total spend flat but shifts toward ROAS above [target]. Output a change list for my approval — at most one budget edit per campaign per day.
The "one edit per day" rule isn't fussiness: editing budgets or audiences more than once a day can reset Meta's ~50-event learning phase and hurt delivery.
A safe 30-day rollout
Connecting in five minutes is easy; trusting an agent with spend should take longer. The rollout we recommend:
| Phase | Days | Scope | What the agent does |
|---|---|---|---|
| Observe | 1–10 | Read-only | Tier 1 + 2 prompts only; you compare its reads against Ads Manager to build trust |
| Propose | 11–20 | Read/write | Tier 3 as drafts — agent proposes, you approve every change in Ads Manager |
| Operate | 21–30+ | Read/write | Agent executes approved playbooks; writes still land paused, still one edit/day |
Never grant the financial scope unless a workflow genuinely needs it.
The one-click alternative: connect inside Soku
If you'd rather not manage connectors per client — and you want the read→diagnose→act discipline above enforced for you — an agent platform handles it. In Soku, Meta Ads sits under Settings → Integrations next to Google Ads, GA4, and TikTok; one Connect click runs the same Meta Business OAuth, no config file.
The payoff is for agencies: after connecting, you assign each ad account to one or more brands, so the agent always acts on the right account — see the multi-brand mapping in What Meta's Official MCP Means for AI Ad Teams.
Which connector should you actually use?
The official server isn't the only option, and it isn't always the fastest to set up. For a side-by-side on setup time, auth model, and safety, see Best MCP Servers for Meta Ads, Ranked by Setup Time. To connect specifically through Claude, see How to Connect Claude to Meta Ads via the Official MCP.
FAQ
Do I need a Developer App or App Review?
No. Both the MCP and CLI authenticate through Meta Business OAuth — the old Developer App + App Review path is gone.
Why did my agent create a live campaign I didn't approve?
Almost certainly the CLI, which creates entities active by default. Add --status PAUSED to automated flows. The MCP creates paused.
MCP or CLI — which do I install?
MCP for conversational analysis; CLI for scripted/bulk execution. Most teams run both.
Is it free?
Yes, during the open beta — no published end date or pricing yet.
