Every step, in order, with the reasoning behind it. Read it end to end in about four minutes and you will know exactly what the system does on your behalf — and what it will never do without asking.
01 — The idea
OAuth to Meta Ads. Accounts, Pages and permissions land in the console.
Every action the UI can take is also an MCP tool and a REST endpoint.
Scopes, validation and an audit trail sit between intent and spend.
02 — The logic
You / your assistant
Chat, dashboard, or API call
Ethio Viral Ads MCP + REST
Auth, scopes, validation, audit
Meta Graph API v24
Campaigns, ad sets, ads, creatives
Sync + webhooks
Results flow back into the console
The loop closes: results come back through scheduled sync and Meta webhooks, so the next question your assistant asks is answered with numbers that are minutes old, not days old.
03 — Step by step
Sign up with Google or email. A workspace is created and every table is row-level scoped to your user.
Why: Ad data is money data. Isolation happens in the database, not in the UI — so even a bug in a page cannot leak another workspace's spend.
/auth
Connections → Connect Meta. Meta's consent screen asks for ads_management, ads_read, business_management and Page access. You come back with your ad accounts and Pages listed.
Why: No access tokens are ever pasted by hand. The token is exchanged server-side, stored encrypted, and refreshed for you — a pasted token would expire in an hour and leak in a screenshot.
/connections
Pick the account you want to operate on and the Facebook Page ads will be published from.
Why: Everything downstream — dashboards, API keys, MCP tools — acts on the active account. One switch changes the whole console instead of ten separate pickers.
/connections
Overview, Analytics and Meta Ads pull live spend, impressions, reach, clicks and results from the Graph API, plus the last sync time.
Why: Nothing is mocked. If a number looks wrong here, it is wrong in Meta too — that is the point of a single source of truth.
/dashboard
Create a campaign, ad set and ad in one wizard. Upload an image or video and the checklist validates dimensions, format, aspect ratio and duration before Meta ever sees it.
Why: Meta rejects creatives after upload with vague errors. Validating locally turns a 20-minute round trip into an instant red line.
/campaigns
Copy the /mcp URL into Claude, ChatGPT or Cursor and add an API key as the bearer token. The assistant then sees your tools.
Why: MCP is the open standard for giving an assistant real tools. Your assistant does not scrape a dashboard — it calls the same audited functions the UI does.
/setup
Issue a scoped key — create ads, pause/resume, update creative, upload media — and call the REST endpoints from a script or n8n.
Why: Scopes mean a key used by a scheduling script can never spend money it wasn't allowed to spend.
/api-keys
Webhooks push Meta changes back in near real time; a backoff queue retries transient failures; every key action lands in the audit log.
Why: Automation without a paper trail is a liability. You can always answer 'who paused this ad, and when'.
/audit
04 — Talking to it
Pause every ad under 1.2 ROAS and move that budget to Retargeting.
What did we spend yesterday, and which creative had the best cost per result?
Swap the video on the Summer Sale ad for this URL and resume it.
Raise the daily budget on the top ad set by 20% but cap it at $200.
{
"mcpServers": {
"ethio-viral-ads": { "url": "https://ads.ethio-viral.com/mcp" }
}
}Your exact endpoint and config are on the MCP setup page once you sign in.
05 — Guardrails
Meta access tokens never reach the browser; the app holds them server-side.
Each key carries an explicit permission set and can be revoked instantly.
Every database query is filtered by your user id on the server.
Create, pause, resume, creative change, media upload — with result and timestamp.
Creatives and budgets are checked before a single request reaches Meta.
Rate limits and permission blips recover on their own instead of silently dropping.
06 — Operating manual
After you sign in, the Manual page walks the same steps against your own account — with live checkmarks for what is already done, copy-paste snippets for your endpoint, and a troubleshooting section for the errors Meta actually returns.