MCP & API

The dashboard and the two programmatic surfaces work on the same resources. Everything listed under What the surface covers below is reachable from both — with a few exceptions under Where the two surfaces differ below, which is where most of the surprises live. The MCP server mirrors the v4 resource surface, and most of its tools wrap a single v4 operation. An AI client never handles the Secret Key.

​

What the surface covers

Customers and users · identities · purchases · user properties · entitlements · products · remote configurations · experiments and groups · segments · analytics, cohorts and LTV · Apple Ads reports, connection status and campaign changes · exports · events · scheduled reports · integrations · project settings.

​

Where the two surfaces differ

• Apple Ads differs between REST and MCP. REST API v4 supports up to four metrics per daily-series request; the MCP series tool accepts one metric per call. The Apple Ads report is available on all accounts (if yours gets 404 from the report, series or connection reads, contact support); accounts without it receive 404 over REST and a “Resource not found” error through MCP. Campaign changes (pause or enable, keyword bid, campaign daily budget) use MCP tools with the separate apple_ads:write scope, campaign management must be enabled for the account, and the signed-in user must hold the Manage Apple Ads campaigns capability; a project Secret Key alone gets 403 control_forbidden. The report’s metric_filters are REST only. Some Apple Ads features are dashboard only, with no REST endpoint or MCP tool: connecting, reconnecting or disconnecting Apple Ads, Update now, spend-history import, budget usage, CSV export, bulk bid changes and week or month grouping of the daily series. See Apple Ads in REST API v4 and Apple Ads via MCP.
• Some v4 resources are legacy. Screens and automations remain callable for existing integrations, but the products behind them are no longer maintained. They are not a place to build something new.

​

Which one to use

• Your own server code, cron jobs, a warehouse sync — the REST API v4. Start at API reference and Authentication.
• An agent acting on your behalf — the MCP server, so that access is scoped to your account role and revocable. Start at For agents and MCP Server.
• Being told when something changes, instead of polling — webhooks.

​

Guardrails worth knowing before you wire anything up

• Destructive tools do not fire on the first call. Over MCP, delete_*, revoke_*, detach_*, discard_* and the deprecated regenerate_project_secret return a short-lived token addressed to the human operator. Completing the action requires echoing the resource id verbatim and giving a reason, which is recorded in the audit log. The Apple Ads campaign-change tools use the same confirmation for enabling and for every live bid or daily-budget change; pausing runs immediately.
• Secret Keys belong on a server. Never ship one in an iOS, Android or web bundle. Rotate them in the dashboard — see Project keys.
• Rate limits are not one number. SDK requests are throttled on the client — see Rate limits. The Apple Ads report and series are rate limited on both surfaces; over REST a 429 carries Retry-After, while through MCP a refusal returns only the error message. Apple Ads campaign changes have their own per-project limits: 10 per minute, 60 per hour, and per 24 hours at most 20 enables, 20 bid increases and 10 daily-budget increases — see Apple Ads and Apple Ads via MCP.
• v3 is legacy. It still answers for existing integrations and gets no new functionality. Build on v4 — start from API reference; API v3 (legacy) maps each v3 resource to its v4 counterpart.

​

Next steps