Skip to help content
RightMessage
MCP referenceReference

MCP tools for Meta Ads

Read the Ads page, choose ads' segments, review new ads, accept suggested segments, and sync your Meta ad account from an AI assistant.

Available on the Scale and Pro plans.

Updated

View as Markdown

These tools give an AI assistant the Ads page: the same report, the same audience choices, and the same review. Use them to ask which ads need an audience, map them, or check how personalization is doing for your ad traffic.

MCP ads access

The tools are listed only while the active project has Meta Ads connected. Every tool accepts an optional string project_id and follows the shared MCP authorization and project-selection rules. The Ads page needs Scale or Pro.

A tool refuses when Meta Ads isn't available to the project, the plan lacks it, or it isn't connected. The refusal is a tool error whose text is a JSON object an assistant can branch on:

FieldMeaning
errornot_available (Meta Ads isn't turned on for the project), plan_required, or not_connected.
messageThe Ads page's own wording: Meta Ads is not available for this project. followed by a note that Meta Ads is in early access and there is no ads data to read; a plan message ending (requiredFeature: campaigns); or Meta Ads is not connected. Connect it in the dashboard: URL.
canConnecttrue only for not_connected, when the project can connect Meta Ads now.
requiredFeaturecampaigns for plan_required, otherwise null.
connectUrlThe dashboard's Meta Ads connect page for not_connected, otherwise null.
JSON
{"error":"not_connected","message":"Meta Ads is not connected. Connect it in the dashboard: https://app.rightmessage.com/123456789/settings/integrations?tab=apps&app=meta_ads","canConnect":true,"requiredFeature":null,"connectUrl":"https://app.rightmessage.com/123456789/settings/integrations?tab=apps&app=meta_ads"}

Connecting Meta Ads needs a Facebook sign-in, so an assistant can't do it; list-connectable-integrations lists it as not connectable, with that dashboard link.

ToolsWhat they do to your siteAPI token needs
get-ads-reportNothingread or write
set-ad-segments, accept-ad-proposal, accept-new-ad-segmentsPut ad audiences live at oncewrite and publish
dismiss-ad-proposal, reject-new-ad-segments, set-new-ads-mode, sync-adsNothing publishedwrite

Ad audiences go live without publish-config. The three live tools rewrite only the ad audience rules in your live configuration and draft and leave every other draft change unpublished. They never restart a running A/B test. See Turn your ads into audiences.

get-ads-report

Read-only. The Ads page report for the connected ad account: active ads plus ads that delivered in the period, grouped into creatives (ads sharing one tracking link).

ArgumentMeaning
range7, 14, or 30 complete days in the ad account's time zone. Default 30.
goal_idThe goal to count conversions for (gol_…). Omit it to use the Ads page's default: the goal of a campaign with A/B testing on, checking the busiest landing page first and preferring the largest holdback on a page; without one, the goal of the campaign covering the busiest landing page.
crossTwo segment group IDs (dim_…) to cross for coverage and combinations. Omit it for the two groups the most creatives use.
creativesall (default), pending_review, no_audience (a tracking link but no segments), or conflicts (a segment your own rules decide differently).
limit, offsetCreatives and combinations per page, 1 to 100 (default 20), and creatives to skip.

It returns connection (sync state), range, goal, goalStatus, and goals, summary (spend, clicks, site visitors, conversions, cost per conversion, and lift), attention, review (the new-ads mode and how many creatives have pending or clashing segments), proposals (each with an id), creatives, audiences, landing_pages (up to 25), coverage (gaps, each with a briefPrompt for drafting an ad), and combinations.

Each creative has a key, name, ads (each with the id that set-ad-segments takes), trackingLink, health, audience (segments by group, with state live or pending and any conflict), and ruledAudience (segments your own rules give its link). Its copy is in headline, body (the primary text), description (the line under the headline, null when the ad has none), and ctaType, Meta's button type such as LEARN_MORE, where NO_BUTTON or null means no button. Money is {amountE4, currency}: divide amountE4 by 10,000. Ad bodies are cut to 300 characters and thumbnails are left out. Null visitors, conversions, or lift mean not measured, never zero. How lift is measured on the Ads page explains lift labels.

Visitors, conversions, and lift are read in the background and kept for about ten minutes before they're read again. measuring: true means the first read is still running, so those numbers are null: say so and call again in a couple of minutes. updating: true means the numbers come from an earlier read, from minutes to a day old, while a newer one runs.

goal is null when no campaign on the ads' landing pages carries a goal, so ad conversions aren't counted. When the project has live goals all the same, goalStatus is {status: "unavailable", reason: "no_live_campaign_goal", explanation, goalCount}, and the explanation gives the goal count, says to pass goal_id to count one here, and points to get-goal-performance, which reads those goals without a campaign. Don't report that the project has no goals. goalStatus is null otherwise.

set-ad-segments

Chooses an ad's segment in each listed group, as Save and apply does in the Ads page's audience picker. Needs write and publish.

ArgumentMeaning
ad_idRequired integer from a creative's ads[].id.
segmentsRequired list of up to 50 {segment_group_id, segment_id}. A null segment_id clears that group; groups left out keep their mapping.

The choice applies to every ad sharing the ad's tracking link, and classification never overwrites it. Returns the ad's ad_id and segments. An unknown ad returns Ad … not found in the connected ad account. Use get-ads-report for ad ids.

accept-ad-proposal and dismiss-ad-proposal

Both take a required integer proposal_id from the report's proposals and return the updated proposal.

  • accept-ad-proposal creates the new segment (new_segment) or segment group (new_group), maps the proposal's ads to it, and puts them live. An ad mapped by hand in that group keeps its choice. Needs write and publish.
  • dismiss-ad-proposal stops offering the suggestion. Nothing changes in the project. Needs write.

accept-new-ad-segments and reject-new-ad-segments

Both take creative_keys, a required list of 1 to 500 creative keys from the report (use creatives: pending_review), and return the updated review counts.

  • accept-new-ad-segments puts each listed creative's pending segments live. Check each one's conflict first. Needs write and publish.
  • reject-new-ad-segments leaves the creatives without those segments, and classification won't pick them again until the ad's content changes. Nothing was live, so nothing is published. Needs write.

set-new-ads-mode

Takes a required mode: auto puts the segments picked for new ads live at once, after every sync; review keeps them pending until accepted. Publishes nothing and changes no existing mapping. Returns the review counts.

sync-ads

Queues a sync of the connected ad account, as Sync now does. Ads otherwise sync every hour. A project can sync at most three times in ten minutes, shared with the dashboard; a refusal says how many seconds to wait. A connection that needs an ad account chosen or a reconnect is refused with a link to the dashboard.

Returns {"queued": true, "connection": …}. The sync runs in the background, so call get-ads-report later and read connection for its progress. In auto mode, segments picked for new ads go live when it finishes.

JSON
{"name":"set-ad-segments","arguments":{"ad_id":4182,"segments":[{"segment_group_id":"dim_business","segment_id":"seg_agency"}]}}

There's no tool for Personalize with Righty. To build a landing page campaign, an assistant uses the campaign tools and publish-config.

Still need a hand?

Tell us what you’re trying to do and where you’re getting stuck.

support@rightmessage.com