---
title: "MCP tools for Meta Ads"
description: "Read the Ads page, choose ads' segments, review new ads, accept suggested segments, and sync your Meta ad account from an AI assistant."
canonical: "https://rightmessage.com/help/mcp-tools-ads"
last-updated: 2026-11-01
---

# 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.

These tools give an AI assistant the [Ads page](https://rightmessage.com/help/meta-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.

> **Meta Ads is in early access**
>
> Projects in the early access program can connect Meta Ads. If you don't see it and you'd like to try it, email <support@rightmessage.com> and ask for access.

## MCP ads access

The tools are listed only while the active project has [Meta Ads connected](https://rightmessage.com/help/connect-meta-ads). Every tool accepts an optional string `project_id` and follows the [shared MCP authorization and project-selection rules](https://rightmessage.com/help/mcp-authorization-reference). The Ads page needs **Scale** or **Pro**.

A tool refuses with the Ads page's own wording when Meta Ads isn't available to the project (`Meta Ads is not available for this project.`), the plan lacks it (the message ends `(requiredFeature: campaigns)`), or it isn't connected (`Meta Ads is not connected`, with a link to connect it in the dashboard). 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.

| Tools                                                                           | What they do to your site     | API token needs       |
| ------------------------------------------------------------------------------- | ----------------------------- | --------------------- |
| `get-ads-report`                                                                | Nothing                       | `read` or `write`     |
| `set-ad-segments`, `accept-ad-proposal`, `accept-new-ad-segments`               | Put ad audiences live at once | `write` and `publish` |
| `dismiss-ad-proposal`, `reject-new-ad-segments`, `set-new-ads-mode`, `sync-ads` | Nothing published             | `write`               |

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 Meta ads into audiences](https://rightmessage.com/help/meta-ad-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).

| Argument          | Meaning                                                                                                                                           |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `range`           | `7`, `14`, or `30` complete days in the ad account's time zone. Default `30`.                                                                     |
| `goal_id`         | The goal to count conversions for (`gol_…`). Omit it to use the goal of the campaign covering the busiest landing page.                           |
| `cross`           | Two segment group IDs (`dim_…`) to cross for coverage and combinations. Omit it for the two groups the most creatives use.                        |
| `creatives`       | `all` (default), `pending_review`, `no_audience` (a tracking link but no segments), or `conflicts` (a segment your own rules decide differently). |
| `limit`, `offset` | Creatives and combinations per page, 1 to 100 (default 20), and creatives to skip.                                                                |

It returns `connection` (sync state), `range`, `goal` 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). 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](https://rightmessage.com/help/meta-ads-lift) explains lift labels.

## `set-ad-segments`

Chooses an ad's segment in each listed group, as **Save and apply** does in the ad's details. Needs `write` and `publish`.

| Argument   | Meaning                                                                                                                                |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `ad_id`    | Required integer from a creative's `ads[].id`.                                                                                         |
| `segments` | Required 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](https://rightmessage.com/help/mcp-tools-campaigns) and `publish-config`.