# Connect Meta Ads to Your Chipp App (Per-User)

Enable your end-users to connect their own Meta Business accounts to your AI agent using per-user OAuth authentication

---

The Meta Ads MCP integration lets each end-user of your Chipp app connect their own Meta Business account. Your AI agent can then manage ad campaigns, pull performance reports, and take actions on behalf of that specific user -- using their own permissions and attribution.

## How Per-User Meta Ads Access Works

When a user asks your agent to do something with Meta Ads for the first time, the agent prompts them to connect their account. After they authorize, the agent uses their OAuth token for all subsequent calls. Each user's token is stored encrypted and refreshed automatically.

**Important:** Meta Ads MCP access is currently in phased rollout by Meta. If a user's Meta Business account has not been granted access to the MCP API yet, the agent will let them know and suggest they check back later. This is a Meta-side restriction, not a Chipp limitation.

## Prerequisites

Before users can connect, you need to provide a pre-registered Meta OAuth application. Meta does not support Dynamic Client Registration (DCR), so you cannot use the automatic DCR path -- you must supply your own `client_id` and `client_secret`.

1. Go to [developers.facebook.com](https://developers.facebook.com) and create a Meta App.
2. Add the **Marketing API** product and request `ads_read` (and `ads_management` if you need write access).
3. Set your OAuth redirect URI to: `https://dino-mullet.chipp.ai/consumer/mcp/oauth/callback`
4. Add your `App ID` and `App Secret` in your Chipp integration settings (see below).

## Builder Setup

### 1. Create the Integration

In the Chipp builder, go to **Actions** and click **Add MCP Integration**. Enter the Meta Ads MCP server URL:

```
https://mcp.facebook.com/ads
```

### 2. Enable Per-User Accounts

Toggle **Per-user accounts** on. This tells the agent to request each end-user's own OAuth token rather than using a single shared credential.

### 3. Supply Your Pre-Registered Client

Because Meta rejects automatic client registration, supply your credentials:

- **Client ID** -- your Meta App's App ID
- **Client Secret** -- your Meta App's App Secret
- **Scopes** -- at minimum: `ads_read`; add `ads_management` for write access

Click **Save** to persist the configuration.

### 4. Test the Connection

Click **Test Connect with Your Account** in the integration settings. This walks through the OAuth flow using your own Meta account and confirms the integration works end-to-end.

## How Users Connect

### In a Web Chat App

When a user first asks the agent about their Meta Ads, the agent calls a connect placeholder tool that renders an **OAuth Connect card** with a button. The user clicks **Connect Meta Ads**, completes the authorization in a popup, and can immediately retry their request.

### In a Channel (WhatsApp, Slack, SMS, Email)

Channels do not support popup windows. Instead, the agent sends a plain-text authorization link:

```
To connect Meta Ads, use this link (expires in 15 minutes):
https://www.facebook.com/v19.0/dialog/oauth?...
```

The user taps the link, authorizes in their browser, and sends another message to retry. After authorization, the agent sends a confirmation: "Connected to Meta Ads. Send me another message and I'll continue."

## Scopes

| Scope | Access Level |
|-------|-------------|
| `ads_read` | Read campaigns, ad sets, ads, and insights |
| `ads_management` | Create and modify campaigns, ad sets, and ads |
| `business_management` | Access Business Manager assets and settings |

Start with `ads_read` and add additional scopes only when your use case requires write access.

## Token Refresh and Re-Authorization

Chipp automatically refreshes access tokens before they expire. If a token is revoked or the user's permissions change, the agent will prompt them to re-authorize. The re-authorization flow is the same as the initial connection.

## Phased Rollout Notice

Meta is gradually rolling out MCP API access. Your users may see a message like:

> "Meta Ads MCP is not yet enabled for this account. Meta is rolling out access gradually -- please check back later."

This is expected behavior for accounts that have not been granted access. No action is required on your part.

## Security Notes

- All OAuth tokens are encrypted at rest using AES-256-CTR.
- Authorization links expire in 15 minutes and are single-use.
- Each user's token is scoped to their account only -- users cannot access each other's data.
- Tokens are never included in logs, model context, or channel reply text.

## Troubleshooting

| Issue | Resolution |
|-------|------------|
| "Meta rejects DCR" error during setup | Supply your pre-registered App ID and App Secret (DCR is not supported by Meta) |
| User sees phased-rollout message | The user's Meta account hasn't been granted MCP access yet; check back later |
| "Insufficient scope" error | Add the required scope (e.g. `ads_management`) and have the user reconnect |
| Authorization link expired | Ask the user to trigger the connection again by sending another message |