# Viral4All Ads

> A Meta (Facebook and Instagram) ads control room an AI can use safely. It reads performance, pauses waste at once, and asks the owner to approve anything that spends money. The owner's hard limits are enforced on the server.

## Connect
- MCP (Streamable HTTP): https://ads.viral4all.com/mcp. Sign in with OAuth (discovery: https://ads.viral4all.com/.well-known/oauth-authorization-server) or send `Authorization: Bearer sk_meta_…` (an API key from https://ads.viral4all.com/api-keys).
- REST: `GET https://ads.viral4all.com/api/public/v1/tools`, then `POST https://ads.viral4all.com/api/public/v1/tools/{name}` with a JSON body. Same tools and rules as MCP. OpenAPI: https://ads.viral4all.com/api/public/v1/openapi.json
- CLI: `npx -y https://ads.viral4all.com/cli/viral4all-ads.tgz login`, then `npx -y https://ads.viral4all.com/cli/viral4all-ads.tgz tools`.
- Claude Code plugin: `/plugin marketplace add https://ads.viral4all.com/claude/marketplace.json`, then `/plugin install viral4all-ads@viral4all`.
- Steps for every AI app: https://ads.viral4all.com/connect

## Rules for agents
- Changes that spend money or publish return `approve_url` and `confirm_token`. Show the user the summary and the approve_url; nothing changes until they approve. Then call `meta_confirm_action`. Never say a change ran before that.
- `meta_pause_ads` runs at once. New campaigns and copies start paused.
- "Blocked by your limits: …" comes from the owner's limits. Stop and tell the user; only they can change limits.
- Budgets and money are in minor units (cents).

## Tools
- `meta_list_ads`: List Meta ads. List every Meta ad on the connected account with status, budget, spend, impressions, reach, interactions and destination link, plus the owner's goals and the hard limits every change request must stay inside.
- `meta_pause_ads`: Pause Meta ads. Pause one or many live Meta ads, ad sets or campaigns by id.
- `meta_resume_ads`: Resume Meta ads (needs your approval). Ask to restart paused Meta ads, ad sets or campaigns by id.
- `meta_set_budget`: Change a Meta budget (needs your approval). Ask to set the daily or lifetime budget of an ad set or campaign, in minor units (cents).
- `meta_update_creative`: Update a Meta ad's link or creative (needs your approval). Ask to change an ad's destination (website URL or WhatsApp number), copy, call to action, image URL or video id.
- `meta_confirm_action`: Check a pending Meta change. Check what happened to a change prepared by meta_resume_ads, meta_set_budget, meta_update_creative, meta_update_adset or meta_archive: waiting_for_approval, done (with the result read back from Meta), undone, failed or rejected, plus any note the owner left.
- `meta_upload_media`: Upload media to Meta from a URL. Download an image or video from a public https URL, store it, and register it with Meta so it can be used in an ad.
- `meta_create_ad`: Create a Meta campaign. Create a full paused Meta campaign: campaign, ad set with budget and targeting, creative and ad.
- `meta_sync_now`: Refresh Meta data. Pull the latest spend, results and creative details from Meta and report what changed since the last sync.
- `meta_get_insights`: Meta ads report. Performance report at account, campaign, ad set or ad level: spend, impressions, reach, frequency, clicks, CTR, CPC, CPM, results, cost per result, ROAS and every action count.
- `meta_list_campaigns`: List Meta campaigns, ad sets and ads. The full structure: campaigns with their ad sets (budget, schedule, optimization goal) and ads (headline, link), each with spend, clicks, results and cost per result.
- `meta_list_accounts`: List connected ad accounts. Every connected Meta ad account with currency, time zone and whether it can deliver, and which one the tools act on.
- `meta_switch_account`: Switch the active ad account. Make another connected ad account the one every tool and the dashboard act on.
- `meta_search_targeting`: Search Meta targeting. Find interests (with audience size) or locations (countries, regions, cities) to target.
- `meta_list_audiences`: List custom audiences. Custom and lookalike audiences on the ad account with type, approximate size and whether they're ready to use.
- `meta_activity_log`: What changed recently. Recent change requests (waiting, approved, rejected, failed, undone, with the owner's notes) and the ad changes the sync detected, newest first.
- `meta_connection_status`: Meta connection status. Whether Meta is connected, the active ad account, when the login expires and the last sync.
- `meta_duplicate`: Duplicate a campaign, ad set or ad. Make a PAUSED copy (campaigns and ad sets copy what's inside them).
- `meta_update_adset`: Edit an ad set's targeting, schedule or bid (needs your approval). Ask to change an ad set: countries (replace the location targeting), ages, genders, interests (from meta_search_targeting; replaces detailed targeting, [] clears it), name, end time (ISO 8601) or bid cap in minor units.
- `meta_archive`: Archive campaigns, ad sets or ads (needs your approval). Ask to archive by id: they stop for good and leave the active lists.
- `list_campaigns`: List workspace campaign notes. List campaign plans saved in the Viral4All Ads workspace (local notes, not live Meta campaigns; use meta_list_campaigns for those), optionally filtered by status or platform.
- `create_campaign`: Save a workspace campaign note. Save a campaign plan in the Viral4All Ads workspace.
- `update_campaign_status`: Update a workspace campaign note. Change the status label of a campaign plan in the Viral4All Ads workspace.
- `list_posts`: List workspace post drafts. List social post drafts saved in the Viral4All Ads workspace (local notes, nothing is published), optionally filtered by status or platform.
- `create_post`: Save a workspace post draft. Save a social post draft in the Viral4All Ads workspace.
- `performance_summary`: Workspace notes summary. Totals across the campaign plans saved in the Viral4All Ads workspace.

## Pages for the owner
- Approvals: https://ads.viral4all.com/approvals
- Goals & limits: https://ads.viral4all.com/limits
- Privacy: https://ads.viral4all.com/privacy
- Terms: https://ads.viral4all.com/terms