AdPilot MCP
Sign in
Browse documentation
Last reviewed

Connect Apple Ads to AdPilot MCP

AdPilot connects to Apple Ads (formerly Apple Search Ads) with a workspace-owned P-256 signing key. AdPilot generates and encrypts the private key; you register only its public key with an Apple Ads API user that you or your organization controls. The connection test discovers the Apple Ads organizations that user is allowed to access and starts synchronization.

AdPilot supports customer-managed API credentials: you or your organization creates and controls the Apple Ads API user and client, registers the AdPilot-generated public key, and provides the Client, Team, and Key IDs. AdPilot does not currently offer Apple's separate service-provider Sign in with Apple authorization flow.

What you need

Before opening the connection wizard, prepare:

  • an AdPilot workspace and app;
  • an owner-controlled Apple Account invited to Apple Ads with an API role;
  • API Account Read Only access for analysis or API Account Manager for account-wide direct operations;
  • access to the API tab for that invited user;
  • an intentional choice of campaign-group scope if using a limited API role.

If the dedicated user does not exist yet, follow Set up an Apple Ads account and API user. That guide covers individual and organization account ownership, App Store Connect linking, the Account Admin invitation, same-email acceptance, role selection, and Apple-side offboarding. Return here when the API user can see Account Settings → API.

Step 1: generate the signing key

  1. Sign in to AdPilot.
  2. Open Connections → Apple Ads.
  3. Select Generate key.
  4. Copy the complete public key shown in the text area.
  5. Note the fingerprint so you can verify the same key is registered in Apple.

The public key begins and ends with PEM markers. Copy the entire value without removing line breaks. The private key never appears in the browser or MCP response.

Generating a key creates a pending Apple connection. It does not contact Apple or grant access by itself.

Step 2: register the public key in Apple Ads

Sign in to Apple Ads as the invited API user—not the Account Admin unless that admin is also intentionally the API user.

  1. Open Account Settings → API.
  2. Create a client or API authorization.
  3. Use a recognizable name such as AdPilot MCP.
  4. Paste the public key from AdPilot.
  5. Complete Apple’s client-creation flow.
  6. Copy the Client ID, Team ID, and Key ID Apple provides.

Apple’s interface labels can change. The separate Apple account and API-user guide explains how the individual or organization prepares the identity and permission boundary. This page owns the client, key, and identifier steps.

Step 3: enter the Apple identifiers

Return to the AdPilot connection page and enter:

AdPilot field Value from Apple
Client ID The API client identifier
Team ID The issuer team identifier
Key ID The identifier for the registered public key

Copy the values exactly. Do not enter the Apple Ads organization ID in one of these fields. AdPilot retrieves organization IDs from Apple’s user access-control response after authentication succeeds.

Select Connect Apple Ads. AdPilot verifies the credentials before marking the connection active.

What the connection test does

The test:

  1. loads the encrypted workspace signing key;
  2. signs an Apple client assertion with the Client, Team, and Key IDs;
  3. requests Apple API access;
  4. retrieves the user ACL;
  5. stores the organizations visible to that API user;
  6. adopts a valid Apple organization currency and timezone for an unconfirmed workspace locale;
  7. queues configuration and metrics synchronization.

The test does not change campaigns. A successful authentication only proves that the key and identifiers work and that Apple returned accessible organizations.

Wait for configuration and metrics sync

Configuration synchronization imports organizations, campaigns, ad groups, targeting keywords, and negative keywords. Metrics synchronization imports complete-day performance for campaigns, ad groups, keywords, and search terms.

Home and Connections show synchronization health and recent errors. Analytics become useful after:

  • the expected organization is enabled;
  • configuration sync succeeds;
  • campaigns are mapped to an AdPilot app;
  • metrics sync covers the requested complete days.

Manual sync requests are available from Connections. AdPilot also refreshes configuration and metrics on a schedule. Tool responses warn when synchronized data is stale or incomplete.

Map campaigns to the correct app

AdPilot uses the App Store Adam ID as the canonical app identity. When Apple campaign data contains an exact identity match, AdPilot can reconcile it to an onboarded app. Ambiguous, conflicting, or missing identities remain in the campaign mapping inbox.

Review the inbox after the first sync:

  1. Confirm exact matches for the intended app.
  2. Add an app to AdPilot if the Apple-promoted app has not been onboarded.
  3. Investigate conflicts instead of selecting the closest name.
  4. Keep one campaign mapped to only one AdPilot app.

Manual confirmed mappings are not overwritten by automatic matching. Correct mapping is required for app-scoped analysis, profitability, and limits.

Confirm the Apple access boundary

This connection inherits the Apple role and campaign-group scope already assigned to the API user. AdPilot cannot widen that access. If the scope is wrong, return to Set up an Apple Ads account and API user and have an Account Admin correct it before relying on synchronization or direct operations.

Troubleshoot the connection

Authentication failed

  • Confirm the Client ID, Team ID, and Key ID were not swapped.
  • Remove accidental leading or trailing whitespace.
  • Verify Apple has the public key whose fingerprint is active in AdPilot.
  • Confirm the API user still has an API role.
  • If the key was rotated, register the new public key and update any newly issued Key ID.

No organizations were discovered

Sign in as the API user and verify it can see the intended Apple Ads account or campaign groups. Ask the Account Admin to review the user’s scope. A valid key cannot grant access the Apple user does not have.

The wrong organization or currency appears

Review Apple-side user scope and the organizations returned to that user. Confirm the workspace currency and timezone under Settings → Workspace before comparing metrics or setting limits.

Configuration appears but metrics do not

Wait for the first metrics job or trigger a manual synchronization. Confirm campaigns are mapped, the requested range uses complete days, and Connections has no unresolved sync error.

Reads work but writes fail

Read-only Apple roles cannot perform direct operations. If write access is intentional, assign API Account Manager or an appropriate limited API Read & Write role. Then re-test. If Apple permissions are correct, inspect the structured AdPilot error for plan, spend, bid, country, protected-term, or provider validation failures.

Rotate the signing key

Rotation creates a new P-256 key pair and retires the prior active AdPilot key.

  1. Select Rotate key in AdPilot.
  2. Copy the new public key and fingerprint.
  3. Register or replace the public key in Apple Ads.
  4. Update the Key ID if Apple issues a new one.
  5. Re-test the connection.
  6. Confirm synchronization resumes before requesting operations.

Coordinate both sides. Rotating in AdPilot before updating Apple temporarily breaks authentication by design.

Disconnect and offboard

Selecting Disconnect and retain history changes the AdPilot connection status and stops live calls while retaining imported history and audit records.

For complete provider-side revocation, follow the Apple-side offboarding steps in Set up an Apple Ads account and API user. Disconnecting AdPilot alone does not delete or change the customer-owned Apple Account.

How AdPilot secures and audits access

  • Private signing keys are encrypted at rest and hidden from serialization.
  • Only the public key, fingerprint, and generation time reach the browser.
  • Apple ACLs determine visible organizations and campaign groups.
  • Every synchronized row is workspace-scoped.
  • Direct operations are authenticated, validated, limited, and recorded.
  • Key generation, rotation, connection, synchronization, and disconnection create auditable state.

Connection checklist

  • The Apple account and API-user setup checklist is complete.
  • The API user can open Account Settings → API and has the intended scope.
  • The active AdPilot public key is registered in Apple.
  • Client ID, Team ID, and Key ID are entered exactly.
  • The test discovers the expected organization.
  • Configuration and metrics synchronization complete.
  • Campaign mappings are confirmed.
  • Workspace locale and limits are reviewed.
  • A read-only orientation request succeeds before direct operations begin.

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.