AdPilot MCP
Sign in
Browse documentation
Last reviewed

Direct operations, spend limits, and audit

AdPilot MCP can change Apple Ads directly from your AI assistant. Before a write reaches Apple, AdPilot identifies the workspace and app, calculates the operation's effect, checks every applicable limit, and creates an auditable action record.

Limits are guardrails, not campaign settings. Changing a limit does not edit an Apple campaign, and changing an Apple campaign does not automatically rewrite your limits.

Subscription entitlements are separate: they control app and MCP-client counts, history, write access, reports, and sync priority. See Plans, pricing, and subscription limits.

Read-only questions do not change campaigns. When you explicitly request a mutation, the tool executes immediately after its checks pass; AdPilot does not keep a separate proposal or approval queue. Your MCP host may still show its own confirmation prompt. Use Changes to review the resulting action ID and provider response.

The two spend limits

AdPilot can enforce a workspace ceiling and an optional app cap at the same time.

Limit Where to configure it What it covers Is it required?
Workspace monthly spend ceiling Limits Maximum projected exposure across every campaign in the workspace, including unmapped campaigns Required before an operation can increase campaign spend
App monthly ad-spend cap Apps → Strategy → Monetization and financial targets Maximum projected exposure from campaigns mapped to that app Optional; enforced after Confirm strategy

If an app has no confirmed cap, its operations are still protected by the workspace ceiling. With multiple apps, each configured app cap is checked independently and the workspace ceiling is checked against the combined total.

App caps and the workspace ceiling must use the workspace currency. AdPilot does not perform currency conversion when enforcing spend limits.

Draft versus confirmed app caps

Save draft preserves unfinished strategy edits but does not activate a new app cap. Confirm strategy saves the financial target and makes the cap effective for the next MCP operation. No background calculation or additional synchronization is required.

Changing the app's monetization model, trial duration, monetization notes, or RevenueCat connection does not change projected ad spend. Those values guide analysis; campaign status and budgets drive spend exposure.

What “Maximum projected month” means

The Limits page shows maximum budget exposure, not expected spend. It assumes an enabled campaign could spend up to its daily budget on every projected day. Actual Apple delivery may be lower because of demand, bids, targeting, account status, or serving issues.

At a high level:

projected month = actual month-to-date spend + unsynced past exposure + today-through-month-end exposure

AdPilot calculates that value in the workspace timezone:

  1. Actual month-to-date spend comes from synced Apple campaign metrics from the first day of the month onward.
  2. Unsynced past days use the campaign state and budget that existed before the proposed operation.
  3. Today through month-end uses the current state for the Limits page or the proposed post-operation state during an MCP limit check.
  4. New and restored campaigns begin adding exposure on the day of the operation, never retroactively from the first of the month.
  5. Lifetime budgets, when supported and present, bound the remaining exposure after lifetime spend is deducted.
  6. Paused campaigns contribute actual spend already recorded this month but no future daily-budget exposure.

For a campaign without current-month metric rows, AdPilot estimates from the later of the month start or the campaign creation date. This deliberately measures possible budget exposure rather than trying to predict pacing.

Why month-to-date can be $0 while projection is high

Apple metrics use complete calendar days. On the first day of a month, no day in that month has completed yet, so month-to-date can correctly show $0.00. Enabled campaigns still have all days in the new month available to spend, so their maximum projection can be much higher.

For example, if enabled campaigns have combined daily budgets of $13 on August 1:

$13 × 31 days = $403 maximum projected spend

A $100 workspace ceiling does not change that $403 projection. It means AdPilot will reject a new operation that increases exposure while the maximum projection remains above $100.

Mid-month budget-change example

Assume a campaign has:

  • $10 actual spend synced through August 15;
  • an old daily budget of $1;
  • a proposed daily budget of $2 on August 20.

The projection is:

Portion Calculation Exposure
Actual through August 15 Synced spend $10
Unsynced August 16–19 4 × $1 old budget $4
August 20–31 12 × $2 proposed budget $24
Maximum projected month $10 + $4 + $24 $38

The new $2 budget is not applied retroactively to August 16–19.

Which operations trigger spend-cap checks?

Spend caps are checked when the operation increases the affected campaign's remaining exposure.

Operation Spend-cap behavior
Create an enabled campaign Checked from the creation day through month-end
Restore or enable a paused campaign Checked from the restore day through month-end
Increase an enabled campaign's usable budget exposure Checked using the proposed budget
Rename a campaign without budget changes Not a spend increase
Send the same budget value again Not a spend increase
Increase a budget while the campaign remains paused Not an immediate spend increase; a later restore is checked
Reduce an enabled campaign's exposure Allowed even when the workspace is already over a cap
Pause a campaign Allowed; it reduces future exposure

Other correctness rules still apply. For example, a non-spend-increasing update can still fail because of invalid identifiers, unsupported Apple payment-model fields, disallowed countries, stale state, or provider rejection.

Understanding a blocked operation

Every failed mutation retains an action ID in Changes. Spend-policy failures include a stable code and a next step.

Error code Meaning What to do
monthly_spend_ceiling_required No workspace ceiling is configured Open Limits, set a ceiling in the workspace currency, save, and retry
monthly_spend_ceiling_exceeded The proposed workspace projection exceeds the workspace ceiling Reduce campaign exposure or deliberately raise the workspace ceiling
app_monthly_budget_exceeded The proposed projection for the selected app exceeds its confirmed cap Reduce mapped campaign exposure or update and confirm the app cap
app_monthly_budget_currency_mismatch The confirmed app cap does not use the workspace currency Correct the currency and amount under the app strategy, then confirm again

If the Limits page says the projection is unavailable, an enabled campaign may be missing required daily-budget data or a campaign/metric currency may not match the workspace. Synchronize Apple Ads, inspect the campaign data, and retry after correcting the mismatch.

Example: $403 projected with a $100 ceiling

Suppose existing enabled campaigns project to $403, the workspace ceiling is $100, and you create a paused test campaign with a $1 daily budget.

  • Renaming the paused campaign works because it does not increase spend.
  • Sending the same $1 budget works because exposure is unchanged.
  • Changing the paused budget to $2 works while it remains paused.
  • Reducing a live campaign budget works because it lowers exposure.
  • Restoring the $1 test campaign is blocked because it adds up to $31 in a 31-day month, producing a $434 workspace projection.

Raising the ceiling to $450–$500 would permit that restore under the workspace rule, but it would also authorize more potential spend. Raise a ceiling only when the higher total exposure is intentional. Otherwise, lower active campaign budgets or keep the test campaign paused.

Choosing sensible limits

Start from the maximum exposure you are willing to authorize—not only from what campaigns happened to spend last month.

  1. Review the enabled daily budgets and remaining lifetime budgets in Apple Ads.
  2. Decide an optional cap for each app based on its mapped campaign portfolio.
  3. Set the workspace ceiling high enough for the combined intentional app exposure, with only the headroom you accept.
  4. Use a 31-day month when estimating the most conservative daily-budget total.
  5. Revisit limits when adding apps, enabling campaigns, changing currencies, or materially changing daily budgets.

As a quick approximation, a $100 ceiling across a 31-day month supports about $3.22 of combined enabled daily budgets when there is no month-to-date spend or tighter lifetime budget:

$100 ÷ 31 ≈ $3.22 per day

This is only a budget-exposure approximation. The Limits page is the authoritative calculation because it also includes actual spend, synchronization coverage, campaign creation dates, operation timing, statuses, and lifetime budgets.

Saving and recalculation

The projection is not stored as a fixed monthly number. AdPilot recalculates it:

  • whenever the Limits page loads or reloads;
  • after Save limits returns to the page;
  • immediately before an MCP operation that increases spend.

Changing the ceiling changes the threshold, not the projected amount. Changing and confirming an app cap changes that app's threshold, not campaign exposure. Campaign status, daily budgets, lifetime budgets, synchronized spend, and the current date change the projection itself.

Other enforced limits

Spend is only one part of the operational controls:

  • Maximum bid adjustment — absolute keyword and ad-group bid changes are converted to a percentage of the current bid and compared with this limit.
  • Allowed countries — an empty list is unrestricted; otherwise requested campaign countries must be a subset.
  • Protected terms — matching negatives and destructive keyword changes are rejected.
  • Evaluation window — controls when a successful operation is measured against an equal comparison period.
  • Subscription and ownership rules — write entitlement, plan counts, workspace ownership, Apple identifier resolution, and payment-model rules remain mandatory.

Audit, evaluation, and rollback

Every mutation creates an action record before policy validation and provider execution. Open Changes to inspect:

  • Operations — started, succeeded, partial, failed, interrupted, and rollback actions;
  • External — immutable changes detected during Apple synchronization;
  • Activity — control-panel events and finalized MCP calls in one timeline.

Operation details include the action ID, Apple identifiers, actor or MCP client, timestamps, request evidence, redacted provider data, field-level before/after values, structured errors, and evaluation results.

Eligible successful operations can be rolled back from Changes or with rollback_action. Not every Apple mutation is reversible. Before rollback, AdPilot checks that the current provider state can still be reconciled with the recorded change.

Successful operations begin in the measuring evaluation state. After the configured evaluation window, AdPilot stores the measured outcome using equal complete-day periods.

Troubleshooting checklist

When a campaign update is blocked:

  1. Copy the action_id, error code, projected amount, and applicable cap from the MCP result.
  2. Open Limits and compare workspace projection, workspace ceiling, and the app row.
  3. Confirm that the campaign is mapped to the intended app.
  4. Check enabled daily budgets, statuses, lifetime budgets, workspace currency, and the latest Apple sync.
  5. Decide whether the operation genuinely increases exposure.
  6. Reduce exposure or adjust only the cap you intentionally want to change.
  7. Retry the same operation and inspect the new action in Changes.

Do not raise a ceiling merely to make a test pass unless the resulting spend exposure is acceptable for the workspace.

How AdPilot uses limits and audit data

For every direct operation, AdPilot resolves the Apple target, records the attempt, evaluates the proposed state against spend, bid, country, protected-term, ownership, and plan rules, then calls Apple only if all checks pass. Successful changes retain before-and-after evidence for later evaluation and eligible rollback.

Next steps

Official sources

Need help with AdPilot MCP?

Contact support at support@kovacssoftware.com

AdPilot is an independent service and is not affiliated with, endorsed by, sponsored by, or operated by Apple Inc. Apple and Apple Ads are trademarks of Apple Inc.