vTilt
By roleFoundersKnow what to fix firstMarketersSee what happens after the clickCMOsSee what your budget really buys
By businessSaaSTurn signups into active usersEcommerceSee why shoppers abandon cartsAgenciesProve your work to clientsEnterpriseOne customer record for every team
MeasureWeb AnalyticsFind where buyers leaveSession ReplaySee why they left, not just that they didAdsKnow what paid visitors do nextIntegrationsOne snippet feeds your stack
ThinkPeopleOne profile per customerCustomer MemoryvTilt remembers every visitorSite KnowledgeAnswers and audits from your own pages
ActAsk AIAnswers from real behaviorAI ChatChat that knows the visitorEmail CampaignsEmail from real visits
PricingWhy vTiltDocs
Docs / Meta Ads
Getting Started
OverviewInstallInitializeIdentify usersTrack eventsLogout & resetVerify eventsCommon mistakes
Guides
Event forwardingReverse proxyRealtime dashboardSite knowledge
Frontend frameworks
Next.jsNuxt.jsVue.jsReactReact RouterRemixGatsbySvelte / SvelteKitAstroAngularTanStack StartDocusaurus
Backend frameworks
NestJSHonoCloudflare WorkersDjangoFlaskLaravelPhoenixRuby on Rails
Backend languages
PythonPHPRubyElixirGoJava.NET / C#Rust
Stack guides
Vue + PHP
API Reference
Browser SDK
Script bundlesAutocaptureWeb VitalsSession recordingChat widgetFeature readinessRemote configurationDebug logging
Node SDK
Install & setupCapture, identify & aliasContext & shutdownGlobal properties & opt-outError tracking
MCP server
Guides
OverviewAuthenticationOAuthAgent skills (prompts)AI intelligenceSite knowledgeGoogle AdsMeta Ads
Client setup
CursorClaude DesktopVS CodeCodex

Getting Started

OverviewInstallInitializeIdentify usersTrack eventsLogout & resetVerify eventsCommon mistakes

Guides

Event forwardingReverse proxyRealtime dashboardSite knowledge

API Reference

MCP server

OverviewAuthenticationOAuthAgent skills (prompts)AI intelligenceSite knowledgeGoogle AdsMeta Ads
On this page

On this page

  • Connect Meta Ads (required first)
  • Permissions
  • Reading account data
  • More read tools
  • Managing the account (writes)
  • Product catalogs and datasets (opt-in toolsets)
  • Troubleshooting
DocsMCP serverGuidesMeta Ads

Meta Ads

Last updated July 22, 2026

Connect a Meta (Facebook/Instagram) Ads account to a vTilt project, then read insights and manage campaigns, ad sets, ads, product catalogs, and datasets through the vTilt MCP server — no separate Meta Ads MCP server required.

Note

Part of the MCP server docs — the overview lists every MCP tool; this page covers the Meta Ads tools and the one-time connection they require.

vTilt can manage your Meta Ads account (Facebook and Instagram advertising) through the same MCP endpoint your AI client already uses for analytics. There is no second server to run: the meta_ads_* tools live in the meta-ads toolset (plus optional catalog and dataset toolsets). Calls succeed only after you connect an account in project settings (otherwise the server returns feature_disabled).

Important

The Meta Ads tools act on your Meta ad account (campaigns, ad sets, ads, insights, catalogs). They are completely separate from vTilt's on-site analytics, and separate from Google Ads. run_query reads your website's events; meta_ads_get_insights reads your Meta ad account; google_ads_search reads your Google Ads account.

Tip

Once a Meta Ads account is connected to your pinned project, the core meta_ads_* tools appear automatically in tools/list — no enable_toolset step. (This auto-listing is why it works on clients that cache the tool catalogue, like Cursor and Claude.ai.) Catalog and dataset tools stay opt-in: add ?toolsets=meta-ads-catalog / ?toolsets=meta-ads-datasets (or ?toolsets=all) to your MCP URL to include them (see Selecting toolsets). If the core tools aren't listed, the account isn't connected yet, the project isn't pinned, or your key lacks meta_ads:read.

#Connect Meta Ads (required first)

The Meta Ads tools stay hidden until a project has a connected account; once connected, the core tools are auto-listed for that project.

  1. Open Project → Settings → Meta Ads.
  2. Click Connect Meta Ads and complete the Meta consent screen. vTilt requests the ads_read, ads_management, business_management, and catalog_management scopes.
  3. After the redirect, vTilt discovers the ad accounts you can access and lists them. Pick the default ad account the tools should use when a call doesn't name one.

vTilt stores the long-lived access token encrypted at rest and holds the platform app secret server-side. Your AI client never sees or sends credentials — tool inputs accept neither an access token nor a user id.

Warning

Meta long-lived access tokens expire after about 60 days and cannot be refreshed automatically (Meta issues no refresh token). The settings page shows the token expiry and prompts you to reconnect before it lapses. After expiry, Meta Ads tools return feature_disabled until you reconnect.

Tip

Connecting is a one-time, per-project action done by a workspace admin. Linked accounts and the default selection are shared by everyone using that project's MCP connection.

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

After switch_project, check features.meta_ads in the tool response (or call get_context). Call meta_ads_* tools as soon as that flag is true — re-run tools/list only if your MCP client caches the catalog.

#Permissions

Meta Ads access is gated by a dedicated meta_ads permission resource:

ActionWho has itWhat it allows
meta_ads:readmembers and aboveList accounts, read campaigns/ad sets/ads, insights, catalogs, datasets
meta_ads:writeowners and adminsCreate / update / activate campaigns, ad sets, ads, and catalog products

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.

Every tool takes an optional ad_account_id (act_1234567890 or the bare 1234567890 — both work). Omit it to use the project's default account. The account must be one of those linked to the project — call meta_ads_get_ad_accounts to see them.

#Reading account data

  1. meta_ads_get_ad_accounts — see which ad accounts are linked to the project and which is the default.
  2. meta_ads_get_ad_entities — list campaigns, ad sets, or ads (level: campaign | adset | ad) with optional fields, effective_status, and limit.
  3. meta_ads_get_insights — performance metrics (impressions, clicks, spend, reach, CTR, CPC, CPM, actions) for the account or a specific object, over a date_preset or explicit time_range.

#More read tools

ToolDoes
meta_ads_insights_performance_trendInsights split by time_increment to show a metric trend over time.
meta_ads_insights_demographic_breakdownInsights broken down by age and gender.
meta_ads_insights_placement_breakdownInsights broken down by publisher platform and placement.
meta_ads_get_pages_for_businessThe Facebook Pages you manage (a page_id is needed when creating Page-linked ads).

Note

A few official Meta surfaces have no stable public Marketing API endpoint — meta_ads_insights_benchmarks, meta_ads_get_opportunity_score, and meta_ads_get_help_article. These return a structured { "available": false, "reason": ... } envelope (not an error) so an agent can continue gracefully. Use meta_ads_get_insights for first-party metrics and Ads Manager for benchmark / opportunity views.

#Managing the account (writes)

New campaigns, ad sets, and ads are created PAUSED by default so nothing starts spending before you review it. Activate them explicitly with meta_ads_activate_entity.

ToolDoes
meta_ads_create_campaignCreate a campaign (name, objective, special_ad_categories, optional budgets/bid strategy).
meta_ads_create_ad_setCreate an ad set under a campaign (optimization_goal, billing_event, targeting, budgets).
meta_ads_create_adCreate an ad under an ad set (creative — a { creative_id } or a full object_story_spec).
meta_ads_update_entityChange fields on an existing campaign / ad set / ad (rename, budget, bid, targeting, status).
meta_ads_activate_entitySet a campaign / ad set / ad to ACTIVE (start spending).

Tip

Budget fields are in minor units of the account currency (cents) — a $50.00 daily budget is 5000. daily_budget and lifetime_budget are mutually exclusive.

Warning

Setting an entity to ACTIVE starts real spend against your Meta ad account. Review budgets and targeting first, and prefer creating entities PAUSED (the default) until you are ready.

#Product catalogs and datasets (opt-in toolsets)

The meta-ads-catalog toolset (add ?toolsets=meta-ads-catalog) covers product catalog management: create catalogs, add/list/update/delete products, create product sets, and read catalog diagnostics. The meta-ads-datasets toolset (add ?toolsets=meta-ads-datasets) covers dataset (pixel / Conversions API) quality: details, diagnostics, stats, and event coverage. Both require the same meta_ads:read / meta_ads:write permissions.

#Troubleshooting

MessageMeaningFix
feature_disabled (feature: meta_ads)No Meta Ads account is connected, or the token expiredConnect / reconnect in Project → Settings → Meta Ads
invalid_arguments with next: meta_ads_get_ad_accountsThe ad_account_id you passed isn't linked to this projectCall meta_ads_get_ad_accounts and use a listed account, or set a default
{ "available": false } envelopeThe tool wraps a Meta surface with no public Marketing API endpointUse meta_ads_get_insights / Ads Manager as the reason field suggests
The core tools don't appear at allNot connected, no project pinned, or key lacks meta_ads:readConnect the account / pin a project / check your permissions
The catalog or dataset tools don't appearThose toolsets are opt-in and not pinnedAdd ?toolsets=meta-ads-catalog / ?toolsets=meta-ads-datasets to your MCP URL
Reconnect prompt in settingsThe long-lived token expired or was revokedClick Connect Meta Ads again
PreviousGoogle AdsMCP serverNextCursorMCP server