Fama in your AI app

Connect

Every app uses the same address. Apps that support MCP sign-in need nothing else: when you add Fama, you sign in to it.

claude mcp add --transport http fama https://fama.best/api/mcp

{
  "mcpServers": {
    "fama": {
      "url": "https://fama.best/api/mcp"
    }
  }
}

{
  "servers": {
    "fama": {
      "type": "http",
      "url": "https://fama.best/api/mcp"
    }
  }
}

Signing in

Signing in takes a minute, and you choose everything the app gets:

Your Fama account

Sign in, or create a free account on the spot. Every account opens on a sample ad account, a fictional coffee brand with 35 days of data, so you can try Fama in your AI app before connecting anything.

One ad account

The app reaches only the account you pick: the sample account, or a Meta ad account you have connected (how to connect one).

Read only, or read and act

Read only answers questions and changes nothing. Read and act may also pause, switch on and change budgets, inside your limits.

Where you go next

The screen shows the address the app will send you back to, such as claude.ai. If it is not the app you just used, choose Deny.

Each sign-in appears in Fama under Settings, AI tools as a key named after the app. Revoke it there and the app is signed out on its next request.

Tools

14 tools: 9 read, 5 change the account. A read-only sign-in gets only the 9 that read. Each tool tells your app whether it reads or changes, so an app that asks before a change can ask.

• Read account healthReads
  get_account_health

  Billing status, today's spend against what the budgets should have spent by now, and every ad set's delivery over 48 hours, including ones that read ACTIVE but have stopped spending, with the cause when it can be named.

  What your app is told

  Call this FIRST for any question about the account's state, spend or a drop in results. Returns the ad account's billing status, today's spend against what its live budgets should have spent by this hour, yesterday's spend, and every ad set's delivery over the last 48 hours, including ad sets that read ACTIVE but have stopped delivering and the cause when one can be named (a disapproved ad, an unsettled balance). A campaign reading ACTIVE in Ads Manager does not mean it is spending; this tool is how you tell.

• Read performance reportReads
  get_performance_report

  Where the money is going, what is working, which creatives are winning and what needs stopping, for a period against the one before, with what pausing each one saves a day.

  What your app is told

  The answer to the four questions people ask most, for a period against the period before it: where the money is going (spend by campaign and ad set, with shares), what is working (winners: cheaper results than the account on enough spend to trust), which creatives are winning (ads ranked by cost per result, with link CTR and hook rate), and what needs stopping or fixing (spend with no results, results at twice the account's cost, live ad sets that spent nothing, rejected ads, tired creative), each with the sentence and numbers behind it and what pausing it saves a day. Each campaign is judged by its own goal: sales by purchases, traffic by landing page views; leads, awareness and engagement campaigns are never called waste for having no purchases. Call it for 'how are my ads doing', 'what should I stop', 'what is working', 'which creative is best', or before recommending where budget should go. Periods end yesterday except today.

• Read campaign structureReads
  get_campaign_structure

  Every campaign, ad set and ad with ids, status, objective, where the budget lives (campaign or ad set), targeting summary, learning stage and ad copy.

  What your app is told

  Returns every campaign, its ad sets and its ads with ids, configured and effective status, objective, budget (and whether it lives on the campaign as CBO or on the ad set as ABO), optimisation goal, audience temperature, targeting summary, learning stage, and each ad's format, headline, primary text and hook. Use it to find entity ids before drafting a change and to check where a budget lives.

• Read performanceReads
  get_ad_insights

  Performance for any window at account, campaign, ad set or ad level, by day or broken down by age, gender, placement or platform.

  What your app is told

  Performance for a window, at account, campaign, adset or ad level, optionally by day or broken down by age, gender, placement or platform. Every ratio (CTR, CPC, CPM, CPA, ROAS, frequency, hook rate) is computed from raw counts. Windows ending yesterday (last_7d, last_14d, last_30d) exclude today, as Meta's do. Purchases count one action type, never several summed. Rows with no impressions are omitted. Use since/until (YYYY-MM-DD, account timezone) for a custom window instead of date_preset.

• Check creative fatigueReads
  get_creative_fatigue

  Each delivering ad's last 7 days against the 7 before: frequency, link CTR and cost per result, with a verdict of fatigued, watch or healthy.

  What your app is told

  Compares every delivering ad's last 7 complete days with the 7 before: seven-day frequency against the limit (3 for cold traffic, 6 for retargeting), link CTR change and CPA change week over week, and a verdict: fatigued (frequency over the limit and CTR or CPA worsening), watch, healthy, or too_little_data. Call it before recommending new creative or moving budget between ads.

• Check pixel healthReads
  get_pixel_health

  When each pixel or dataset last fired, daily counts per event, whether events carry a value, and whether any arrive through the Conversions API.

  What your app is told

  The account's pixels or datasets: when each last fired, daily counts per event (PageView, ViewContent, AddToCart, InitiateCheckout, Purchase), whether events carry a value, whether any arrive server-side through the Conversions API, and the problems that break optimisation.

• Read autopilot rulesReads
  list_autopilot_rules

  The account's autopilot rules, each with its plain-words description, its mode (dry run, live or off) and when it was last checked.

  What your app is told

  The account's autopilot rules: standing orders checked every hour (for example, pause any ad set that spent R200 with no purchases in 3 days). Each with its plain-words description, its mode (dry_run records what it would do, live acts, off does nothing) and when it was last checked.

• PauseChanges the account
  pause

  Pauses a campaign, ad set or ad. Pausing only stops spend, so it happens at once, unless you have Fama ask before every change or read-only mode is on.

  What your app is told

  Pauses a campaign, ad set or ad in Meta. Pausing only stops spend, so it is always inside the limits and happens at once (unless the account is set to confirm every change, or read-only mode is on). Pausing the only active ad in an ad set stops the whole ad set; the result says so. Use it when the person asks, or when they agreed to your recommendation. Inside the limits the person set, it happens at once and the result says what Meta now reports. Over a soft limit it waits for the person to confirm; past a hard limit (the account's daily cap, read-only mode) it is refused. Read `result` before saying what happened.

• Switch onChanges the account
  switch_on

  Switches a paused campaign, ad set or ad back on. Refused when it would take the account's live daily budgets over its cap.

  What your app is told

  Switches ON a paused campaign, ad set or ad, so it can spend. Use it only when the person asks for it or clearly agrees. The account's daily cap is a hard limit: a switch-on that would take live daily budgets over it is refused. Something switched on under a paused campaign or ad set will not spend until that is on too; the result says so. Inside the limits the person set, it happens at once and the result says what Meta now reports. Over a soft limit it waits for the person to confirm; past a hard limit (the account's daily cap, read-only mode) it is refused. Read `result` before saying what happened.

• Set daily budgetChanges the account
  set_daily_budget

  Sets the daily budget on the campaign or ad set that holds it. Lowering happens at once; a raise over your limit waits for you; a raise past the account's cap is refused.

  What your app is told

  Sets a new daily budget on a CBO campaign or an ABO ad set (use the entity that actually holds the budget). Lowering is inside the limits and happens at once. A raise over the person's single-raise limit (25% by default) or over the per-campaign limit waits for them to confirm; a raise that takes the account over its daily cap is refused. A change over 20% can restart Meta's learning phase. Inside the limits the person set, it happens at once and the result says what Meta now reports. Over a soft limit it waits for the person to confirm; past a hard limit (the account's daily cap, read-only mode) it is refused. Read `result` before saying what happened.

• Copy ad setChanges the account
  duplicate_ad_set

  Copies an ad set with its ads, always paused, so a winner can be scaled without resetting its learning. Meta copies ad sets of up to 3 ads this way.

  What your app is told

  Copies an ad set with its ads, always created PAUSED, optionally renamed and, for ABO ad sets, with its own daily budget. The usual way to scale a winner without resetting its learning. The copy spends nothing until it is switched on (switch_on). Meta copies an ad set with its ads in one step only when it has 3 ads or fewer; for a bigger one, say so and point the person to Duplicate in Ads Manager. Inside the limits the person set, it happens at once and the result says what Meta now reports. Over a soft limit it waits for the person to confirm; past a hard limit (the account's daily cap, read-only mode) it is refused. Read `result` before saying what happened.

• Create autopilot ruleChanges the account
  create_autopilot_rule

  Turns a standing order in plain words into a rule checked every hour. It starts in dry run and changes nothing until you switch it to live.

  What your app is told

  Turns a standing order the person describes into an autopilot rule, checked every hour. It is saved in DRY RUN: it records what it would do but changes nothing until the person switches it to live on the Autopilot screen. The result shows what it would match right now; tell them. level: campaign, adset or ad. window_days: 1 (today), 3, 7, 14 or 30, always including today. conditions (all must hold, 1 to 4): metric is one of spend, impressions, link_clicks, link_ctr (percent), cpc, cpm, frequency, landing_page_views, purchases, cpa, roas, results and cost_per_result (results by each campaign's own goal); op is gt, gte, lt, lte or eq; money values in the account currency's major units (200 means R200.00). A cost metric never matches something with no results, so 'spent R200 and no purchases' is spend gte 200 plus purchases eq 0. A rule judging a cost or a rate must also have a floor (spend, impressions or link clicks at least something), or it is refused. action: pause, alert (no change), lower_budget or raise_budget with percent 5 to 50 (budget rules only at campaign or adset level; raises only where the person allowed autopilot to raise in Settings). cooldown_hours (default 24) is how often it may act on the same thing. Ask the person for any number they did not give.

• List changesReads
  list_changes

  Changes on the account: by default the ones waiting for you to confirm, with a link to each; or what was made, refused or failed, and who asked.

  What your app is told

  Lists changes for this ad account, newest first: by default the ones waiting for the person to confirm (over a limit, or from a key that may only propose), with a link where they confirm each. 'done' lists what was made, refused or failed, and by whom (the chat, an AI tool, autopilot, a person).

• Read a changeReads
  get_change

  One change: whether it was made, is waiting, was refused or failed, what it changed, and what Meta reported afterwards.

  What your app is told

  One change by id: whether it was made, is waiting, was refused or failed, what it changed, the limits it met, and what Meta reported afterwards. Call it after the person says they confirmed something, before saying it is live.

Limits and safety

An AI app works under exactly the limits Fama's own chat does, and you set them in Fama:

• A daily cap on the account. The total of its live daily budgets can never go above it. Nothing in the product lifts it except you, in Settings.
• Raises wait. A single budget raise of more than 25% (you can change the figure), or any budget above your per-item ceiling, waits for you to confirm it in Activity.
• No confirm tool. A change that waits is confirmed by you in Fama, never by the app that asked for it.
• Four kinds of change only. Pause, switch on, set a daily budget, and a paused copy of an ad set. Fama cannot create ads or change targeting or creative.
• Autopilot rules start in dry run. A rule an app sets up records what it would do; only you switch it to live.
• A kill switch. Read-only mode refuses every change; ask-me-first makes every change wait.
• Everything is logged. Activity shows every change, which app asked, and what Meta reported afterwards.

Rate limits: 150 requests every five minutes for each sign-in or key, and 60 changes an hour from AI apps on one workspace. A workspace holds up to 10 keys and sign-ins together.

Use a key instead

For apps that cannot sign in, or scripts, make a key in Fama under Settings, AI tools: read only or read and act, for one ad account. It is shown once. Send it as a bearer token:

claude mcp add --transport http fama https://fama.best/api/mcp \
  --header "Authorization: Bearer mp_your_key"

Apps that take only an address can use the connector address Settings shows, which contains the key: treat it like a password, and prefer signing in where the app supports it.

Your data

Fama sees only what your app sends in each tool call, not the rest of your conversation. It reads your ad account through Meta's Marketing API with the access you gave it, and keeps every change in the activity log.

Sign-in codes, tokens and keys are stored only as hashes, and your Meta access token is encrypted at rest. The privacy policy has the details, and this page explains how to delete your data.

Troubleshooting

For developers

Transport

Streamable HTTP at https://fama.best/api/mcp, stateless, JSON responses, POST only. Protocol versions 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05.

Without a token

Every request, initialize included, gets 401 with WWW-Authenticate: Bearer resource_metadata="…", so apps start signing in from the first request. An expired token adds error="invalid_token".

Discovery

https://fama.best/.well-known/oauth-protected-resource/api/mcp (RFC 9728) and https://fama.best/.well-known/oauth-authorization-server (RFC 8414).

OAuth 2.1

Public clients only, identified by a client ID metadata document (an https client_id, as Claude's published identity and Claude Code use) or by dynamic client registration (RFC 7591); PKCE with S256 required; scopes read and act. Access tokens last 1 hour; refresh tokens rotate on every use and lapse after 60 days unused, and one used twice ends the sign-in. Loopback redirect addresses match on any port. Revocation per RFC 7009.

Registry

Listed in the official MCP Registry as best.fama/ads.

Support

Email hello@fama.best. Tell us which app you connected from and what it said.