Meta Ads (Facebook & Instagram)

1. Open Settings → Integrations → Meta Ads.
2. Click Connect with Meta for reporting plus campaign-management capability, or Read-only for reporting only.
3. On Meta's consent screen, choose the Businesses, Pages, and Ad Accounts ShopMCP should access. For agencies, choose all accounts that may need to be assigned across client workspaces.
4. Back in ShopMCP, select the exact ad accounts to attach. Each selected account becomes a separate connection so Claude and ChatGPT can route prompts by account without an ads dashboard.

You'll end up pasting three things into Settings → Integrations → Meta Ads:

• System User access token — a long-lived token generated by a System User you create inside Business Manager. Looks like a 200+ character string starting with EAA….
• Business portfolio ID — the numeric ID of your Business in Business Manager (e.g. 1234567890123456). Sometimes still labelled “Business Manager ID” in older menus.
• Ad Account ID (optional) — restricts ShopMCP to a single Ad Account, e.g. act_1234567890. Leave blank to give ShopMCP every Ad Account the System User can see.

To produce a valid token, three things need to line up: a Business app at developers.facebook.com, that app added to your Business portfolio, and a System User in that Business with access to your Ad Accounts. Steps 1–6 walk through each. If you already have a Business App linked to your portfolio (most Shopify ↔ Meta installs and Conversions API setups create one), you can skip step 1.

• Admin role on a Meta Business portfolio at business.facebook.com. Anything less can't create System Users or install apps.
• A verified Facebook account in good standing — the developer flow uses your personal Facebook identity to claim ownership of the App, even though the App itself runs on behalf of the Business.

Skip this step if Business Settings → Accounts → Apps inside Business Manager already lists an app you control. Otherwise:

1. Open developers.facebook.com/apps/creation. If this is your first developer App, Meta walks you through a short developer-account registration first — agree to the policies, verify your Facebook account by phone or email, done.
2. App details — give it a name (e.g. Acme Marketing API) and a contact email. Click Next.
3. Use cases — pick Other. The use-case picker shortcuts add permissions for specific Meta products (Login, WhatsApp, etc.); for the Marketing API the cleanest path is to start blank and add the product manually. Click Next.
4. App type — pick Business. This is mandatory for Marketing API access; Consumer and Gaming can't request ads_read. Click Next.
5. Business portfolio — pick the same Business you'll be creating the System User in. This step matters. If the dropdown is empty, click Create new and follow the prompt; you can also skip and link the Business later (step 2). Click Create app.
6. On the new app dashboard, scroll to Add products to your app, find the Marketing API card, and click Set up. No further configuration is needed — adding the product is what unlocks ads_read / ads_management in the System User token scope picker later.
7. (Optional) From the left nav, open App settings → Basic and copy the App ID. You won't paste it into ShopMCP, but it's useful when troubleshooting which app a token belongs to.

If the dropdown in step 1.5 had your Business in it and you picked it, the link is already done — skip ahead. Otherwise, the System User will not be able to generate a token for this App until you do this.

1. Open business.facebook.com/settings/apps (path: Business Settings → Accounts → Apps).
2. Click Add → Connect an app ID. Paste the App ID from step 1.7 and click Add app. Meta confirms the link instantly.

Open business.facebook.com/settings/system-users (path: Settings → Users → System users; older guides call this “Business Settings → System Users”, same screen).

1. Click Add (in some accounts the button is labelled Add new system user).
2. Type — if Meta asks, pick Regular system user. The other option, Admin system user, is a separate concept — don't confuse it with the role picker on the next screen.
3. Name — Meta's profile-name policy rejects names with too many capital letters, so ShopMCP and SHOPMCP both fail. Use something mostly lowercase, e.g. ShopMCP integration, shopmcp reporting, or just Reporting.
4. Role — choose Admin if Meta allows it. Each Business is capped at one Admin System User, so if Meta refuses (“You already have an admin system user”), choose Employee instead. Employees work fine for ShopMCP — you just have to assign Ad Accounts explicitly in step 4.
5. Click Create system user.

Required for Employee System Users. For Admin System Users this happens automatically for every Ad Account in the Business — but assigning explicitly anyway is good hygiene.

1. With the System User selected, click Add Assets in the right-hand panel.
2. Pick Ad Accounts in the asset-type sidebar. Tick every Ad Account ShopMCP should access.
3. Permissions — toggle on View performance at minimum. Add Manage campaigns only if you plan to enable ShopMCP's write tools later. Don't toggle Manage Ad Account— ShopMCP doesn't need account-level admin.
4. Click Save changes. The grant is effective immediately.

Still on the System User detail page, click Generate new token.

1. App— pick the App from steps 1–2. If it's not in the dropdown, the App isn't linked to this Business portfolio yet — go back and finish step 2.
2. Token expiration — pick Never. System User tokens are designed to persist; the 60-day option is there for compatibility with short-lived flows you don't need.
3. Available scopes — tick:
   • ads_read — required for ad account, campaign, ad, creative, audience, catalog, pixel, and paid-insight tools.
   • pages_read_engagement — required for scoped Facebook Page posts and organic engagement counts.
   • pages_read_user_content — recommended for fuller organic Page activity reads, including Page-owned post content.
   • read_insights — needed for Page Insights metrics when Meta/App Review makes it available for your app.
   • ads_management— only if you'll enable write tools later. Skip otherwise; principle of least privilege.
   • business_management — recommended. Lets ShopMCP enumerate Ad Accounts across multiple Businesses the token can see (matters for agencies and holding companies).
4. Click Generate token.
5. Copy the token now. Meta only shows the value once. If you close the dialog without copying, generate a new token; the old one stays valid until you click Revoke next to it.

Open business.facebook.com/settings/info (path: Settings → Business info). Copy the numeric Business portfolio ID shown at the top — 15-16 digits, e.g. 1234567890123456.

Only needed if you want to scope ShopMCP to a single Ad Account. Open business.facebook.com/settings/ad-accounts and click an Ad Account in the list — its ID is shown directly under the name, prefixed with act_. Pass the value with the act_ prefix when you paste it into ShopMCP (e.g. act_1234567890).

Open Settings → Integrations → Meta Ads. Fill in the System User access token (step 5), Business portfolio ID (step 6), and optionally an Ad Account ID (step 7). Click Connect Meta Ads.

On submit, ShopMCP calls GET /me on the Meta Graph API to confirm the token is valid. 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 write tools for campaign, ad set, ad, creative, image, audience, budget, status, and duplicate operations. They're compiled in but never registered until you flip the Allow writes toggle on the integration page — and the connected Meta token has ads_management in its scope. Catalog reads are available, but catalog write tools are deferred until Meta exposes a compatible reviewed permission path for this Business Login setup.

Each write tool is locked to a hand-written, field-level input allowlist. For example, meta_ads_update_campaign_budget accepts daily_budget and lifetime_budget — and nothing else. Unsupported fields are rejected at the input schema layer before any HTTP request is built. If a prompt injection convinces the LLM to call a write tool with disallowed fields, the Zod validator drops the request on the floor.

The Page tools do not read every Page your Facebook login can access. ShopMCP first asks Meta for the Pages available to the selected ad account, then only reads posts, engagement counts, and insights for those scoped Pages. If one ad account can promote multiple Pages, Claude or ChatGPT will ask you to choose a page_id or page_name.

Typical prompts include Show recent Facebook Page activity for BAA, List organic posts for Boat Accessories Australia, and Get Page insight metrics for the last 7 days.

System User access tokens never expire when you choose Never in step 5.2. Unlike short-lived User tokens, System User tokens are designed for server-to-server integrations and persist until manually revoked.

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

• “Profile names can't have too many capital letters”— Meta's profile-name policy. Use a mostly-lowercase name like ShopMCP integration or Reporting.
• “You already have an admin system user” — each Business is capped at one Admin System User. Pick Employee instead and assign Ad Accounts explicitly (step 4).
• App dropdown is empty when generating the token— the App isn't linked to this Business portfolio. Go back to step 2 and use Business Settings → Accounts → Apps → Add → Connect an app ID.
• “Invalid OAuth access token” (401) on connect — the token has been revoked, the System User was deleted, or you pasted only part of the token. Regenerate and re-paste — Meta tokens are 200+ characters; truncated copies fail validation.
• “Permissions error” (403)— the token doesn't have the scope ShopMCP needs. Inspect it in the Graph API debugger and confirm the relevant scope is listed: ads_read for ad tools, pages_read_engagement and pages_read_user_content for Page posts, and read_insights for Page Insights. If missing, fix App Review access and regenerate.
• “(#100) Tried accessing nonexisting field … on node type AdAccount” — the System User doesn't have View performance on that Ad Account. Go back to step 4 and tick the Ad Account.
• “Application request limit reached” (429)— Meta is rate-limiting the App. ShopMCP doesn't auto-retry on 429. Wait a few minutes; if it keeps happening, check whether other integrations share the App and are eating the rate-limit budget.
• “OAuthException”— usually the App isn't approved for the requested permission, or it's still in development mode. Open it at developers.facebook.com/apps and confirm the relevant Marketing API permissions show Standard Access in App Review → Permissions and Features.