Meta Ads (Facebook & Instagram)

In Meta Business Manager, go to Business Settings → Users → System Users → Add. Give it a descriptive name like ShopMCP. Set the role to Admin for full ads access, or Employee if you only need read access — in that case, make sure the user has at least ads_read permission on the relevant ad accounts.

On the System User you just created, click Generate New Token. Select the Meta app associated with your business (or create one at developers.facebook.com if you don't have one). Grant the following permissions:

• ads_read — required for all read tools
• ads_management — required only if you plan to enable write tools later

Click Generate Token. Copy the token immediately — Meta will not show it again. Store it somewhere safe until you paste it into ShopMCP.

In Meta Business Manager, go to Business Settings → Business Info. Copy the numeric Business Manager ID displayed at the top of the page (e.g. 123456789012345). ShopMCP uses this to scope API requests to your business.

Open Settings → Integrations → Meta Ads and fill in:

• System User access token — the token from step 2
• Business Manager ID — the numeric ID from step 3
• Ad Account ID (optional) — if you want to restrict ShopMCP to a single ad account, enter its ID (e.g. act_123456789). Leave blank to allow access to all ad accounts the System User can see.

On submit, ShopMCP calls GET /me on the Meta Graph API to confirm the token is valid and has the required permissions. A successful verification persists the credentials encrypted-at-rest (KMS envelope) and flips the Meta Ads module to Connected for every API key in the workspace.

ShopMCP's Meta Ads package includes three write tools — meta_ads_pause_campaign, meta_ads_resume_campaign, and meta_ads_update_budget. These are compiled in but never registered in v1. The runtime calls registerMetaAdsTools({ allowWrites: false }) regardless of plan tier.

Each write tool is locked to a hand-written, field-level input allowlist. For example, meta_ads_update_budget accepts daily_budget and lifetime_budget — and nothing else. Campaign objective changes, audience modifications, and creative updates are all rejected at the input schema layer before any HTTP request is built. This is deliberate: if a prompt injection convinces the LLM to call the tool with disallowed fields, the Zod validator drops the request on the floor.

System User access tokens never expire unless explicitly revoked. This is a Meta platform feature — unlike short-lived User tokens, System User tokens are designed for server-to-server integrations and persist indefinitely.

• Revoke by deleting the System User. In Business Manager, go to Business Settings → System Users, select the user, and click Remove. All tokens issued to that System User are immediately invalidated.
• Revoke a single token. On the System User page, find the token in the list and click Revoke Token. The System User itself remains active — only that specific token stops working.
• Rotate periodically.Even though the token doesn't expire, consider generating a new one and revoking the old one every ~90 days as a security best practice.

• "Invalid OAuth access token" (401) — the token has been revoked or the System User was deleted. Generate a new token in Business Manager and reconnect in ShopMCP.
• "Permissions error" (403) — the System User is missing the required permission scope. Go to Business Manager, edit the System User, and ensure ads_read is granted. If you need write tools, also grant ads_management.
• "Application request limit reached" (429) — Meta is rate-limiting your app. ShopMCP does not retry automatically on 429 by design. Wait a few minutes and try again. If this happens frequently, check whether other integrations are sharing the same app and consuming your rate limit budget.
• "OAuthException" — this typically means the Meta app is not approved for the ads_read permission, or the app is still in development mode. Go to developers.facebook.com and ensure the app is live and has the required permissions approved through App Review.