@apex-inc/mcp-server 0.39.0 → 0.40.0

package/skills/apex-integration-cookbook/SKILL.md

@@ -369,3 +369,21 @@ const live = await apex.links.list({ enabled: true });
 ```
 
 Experiments live under `apex.experiments.*` (`list`, `get`, `getResults`, `activate`, `promote`, `assignVariant`, `checkConflicts`, `checkLiveTests`). `apex.mobile` is reserved for install attribution and SKAN values.
+
+## Recipe: Buyer lists on ad platforms (MCP)
+
+A buyer list is one of the shop's segments, kept on Meta, Google or LinkedIn by Apex and refreshed every day. The shop picks it on an ad set once, to leave buyers out of prospecting or to find more people like them. Same as Attribution → Ad platforms → Who sees your ads.
+
+1. `list_audiences` shows each list, its segment, the goal it was made for, the platforms it goes to, the platforms it actually reached, and how many people it holds back.
+2. `update_audience` changes where a list goes (`platforms`) or how many people are held back (`holdout_percent`: 0, 5, 10 or 20). 0 stops holding anyone back. Dropping a platform the list already reached deletes the list there, which cannot be undone. Without `confirm_delete: true` the tool changes nothing and lists those platforms in `would_delete_from`; ask the shop, then call again with it. A platform that refuses the delete comes back in `refused`.
+3. `remove_audience` takes the list off every platform it reached. It cannot be undone and any ad set using it stops using it, so ask the shop first and pass `confirm: true` only after they say yes. A platform that refuses comes back in `refused`; tell the shop to delete it there by hand.
+
+A held-back list that belongs to an Ad holdout experiment is the experiment's. These tools refuse it; pause or archive the experiment instead.
+
+When someone asks to be deleted or opts out of ads, Apex takes them off every list right away. If a platform refuses or isn't connected, they stay on it, and `list_audience_removals` shows them: how many each list still owes per platform, why, and what the platform said. Apex retries every day for 30 days, then stops (`stopped_retrying`) and waits for the shop. Tell the shop plainly that people who asked to be removed are still being shown ads there. If `why` is `not_connected`, the shop reconnects the platform; then call `retry_audience_removals` with the list's id, which also tries the ones Apex stopped on. Its `still_owed` says who is left.
+
+To add a list, start from what the shop wants its ads to do. `list_audience_goals` returns four goals: `win_back` (bought, but not within `window_days`, which comes from the shop's kind of business), `stop_paying` (everyone who ever bought, left out of ads for new people), `interested` (added to cart or started checkout in the last 30 days and never bought; `locked` until those events arrive) and `lookalike` (everyone who bought, with what each spent, for a Meta value-based lookalike). Each says where its list can go now (`networks`) and which lists the shop already made for it (`lists`). If a goal already has a list, ask whether they want another rather than a copy. Tell the shop who goes and where, then call `add_audience` with the goal and `confirm: true`. Apex saves the goal's rule as a segment named after the list, so the shop can change who's on it in Segments, and sends the list right away unless `send_now: false`. The result's `sent` says how many people each platform took. Spend goes only to Meta: neither LinkedIn's nor Google's list upload takes it, so a list that carries spend reaches them as the same people without it. Say so rather than calling a Google or LinkedIn list value-based.
+
+Before sending one of the shop's own events (a trial start, a booked demo) to its ad platforms, call `preview_ad_platform_send` with the event name and what it means (`purchase`, `lead`, `signup`, `subscription`, `add_to_cart`, or `something_else`). Show the shop which platforms would hear it, under what name, and which can't and why, plus the `estimate`: how often it happened in the last 30 days and what a month of sends costs at the shop's price. It saves and sends nothing.
+
+When the shop says yes, call `add_ad_platform_send` with the same event and meaning and `confirm: true`. It saves the send on the shop's Conversion for that event, so experiments and goals count the same thing. If that Conversion already means something else, the tool is refused; change the meaning on Conversions first rather than picking a different meaning to get around it. For `something_else`, Apex makes the conversion on Meta itself so campaigns can optimize for it; if `couldnt_make` comes back, tell the shop Meta's reason (usually a reconnect). A platform showing `not_agreed` only hears it after the shop agrees on Attribution → Ad platforms; the tool never agrees for them. If `without_consent_answer` is `not_sent`, only events that carry a yes go out. `list_ad_platform_sends` shows what is being sent, and `remove_ad_platform_send` stops one and keeps the Conversion.