Guide / codex
Connect Codex to Meta Ads MCP: Setup and First Analysis
Connect Codex to the official Meta Ads MCP with OAuth, verify account access, and run a safe, read-only seven-day advertising performance analysis.
This tutorial shows you how to connect Codex to Meta's official Ads MCP. When you finish, Codex will be able to list the Meta ad accounts you can access and retrieve performance data for placements such as Facebook and Instagram.
Setup normally takes 5–10 minutes. You do not need custom code or a Meta Developer App, and you should never paste a Meta password or token into Codex.
What you will have when you finish
Meta Adsappears as connected in Codex's MCP server list.- Codex can list the Meta ad accounts available to your user.
- Codex can report the last seven complete calendar days in the account's time zone and currency.
- Your first workflow reads data without creating, changing, pausing, or deleting ads.
Before you start
| What you need | Minimum requirement | How to verify it |
|---|---|---|
| Codex | A desktop app with Codex is installed | Open the app, enter Codex, and start a new chat |
| Meta login | A working Facebook login | Sign in through your browser and complete any two-factor prompt |
| Ad account access | Permission to view performance for the target account | Open that account and view a report in Meta Ads Manager |
| Browser | Able to open the Meta OAuth consent flow | Temporarily disable extensions that block sign-in pop-ups |
This guide uses the Codex desktop interface. If it is not installed yet, follow the official OpenAI desktop app guide first.
Step 1: Install and open Codex
Skip to the next step if you can already use Codex in the desktop app.
- Download the desktop app for macOS, Windows, or Linux from the official OpenAI page.
- Install and open the app, then sign in with your OpenAI account.
- Select Codex in the app.
- Select New chat.
Checkpoint: You should see the Codex composer and be able to send a test message.
Step 2: Add the Meta Ads MCP server
- Open Settings in Codex.
- Select MCP servers.
- Select Add server.
- Enter the following values:
| Field | Value |
|---|---|
| Name | Meta Ads |
| Type | Streamable HTTP |
| URL | https://mcp.facebook.com/ads |
- Save the server.
- Select Restart so Codex reloads the MCP configuration.
Checkpoint: Meta Ads should appear in the MCP server list. A message saying that authentication is required is expected at this stage.
If your Codex version does not yet show the visual setup form, add the server to the global ~/.codex/config.toml file instead:
[mcp_servers.meta_ads]
url = "https://mcp.facebook.com/ads"
default_tools_approval_mode = "writes"
Restart Codex after saving. Keep this in your global configuration rather than a project repository so another project does not automatically inherit access to your advertising account.
Step 3: Complete Meta OAuth authorization
- Select Authenticate next to the
Meta Adsserver. - When your browser opens, sign in with the Facebook user that can access the target ad account.
- Review the accounts and permissions shown on the consent page. Authorize only the accounts needed for this analysis.
- Complete the consent flow and return to Codex.
- If Codex still shows a pending state, reopen the MCP server list or restart the app once.
Checkpoint: Meta Ads should no longer request authentication and should appear enabled or connected.
OAuth does not grant new Meta account permissions. The connector can only access accounts already available to the Facebook user. For a team account, ask the Business Portfolio administrator to assign access before continuing.
Step 4: Confirm that Codex loaded the tools
Start a new Codex chat and enter:
/mcp
Find Meta Ads in the result. If the server and its tools are visible, Codex has loaded the connection.
Do not skip this check. If the server is not connected, a normal question may produce a general answer instead of reading your real account.
Step 5: List your accessible ad accounts
Paste this prompt into Codex:
Use only read-only tools from Meta Ads MCP to list the Meta ad accounts
available to the currently authorized user.
For each account, return:
- account name
- ad account ID
- account status
- time zone
- currency
Mark any unavailable field as "unavailable" instead of guessing.
Do not create, change, pause, or delete any ad, ad set, campaign,
audience, bid, or budget.
Successful result: Codex should return at least one account you recognize. Meta ad account IDs commonly begin with act_. Compare the account name, time zone, and currency with Meta Ads Manager.
If several accounts appear, copy the exact act_... ID you want to analyze so the next request cannot silently use the wrong account.
Step 6: Run your first read-only analysis
Replace act_1234567890 with the ad account ID you just verified:
Use only read-only tools from Meta Ads MCP to analyze ad account
act_1234567890.
Requirements:
1. First confirm the account name, account ID, time zone, and currency.
2. Use the last seven complete calendar days ending yesterday in the
account's time zone. Do not include today.
3. At campaign level, report status, spend, impressions, clicks, CTR,
CPC, conversions, CPA, purchase conversion value, and ROAS.
4. Sort campaigns by spend descending and include an account total row.
5. State the click definition, conversion event, and attribution context.
If the API does not return a metric, mark it "unavailable" instead of 0.
6. Finish with no more than three anomalies worth human review, but do
not carry out any optimization.
Do not create, change, pause, or delete any ad, ad set, campaign,
audience, bid, or budget.
A result that is safe to use should identify:
- The exact ad account, not only its display name.
- The start and end dates and whether today was excluded.
- The reporting time zone and currency.
- Whether each metric is an account total or a campaign value.
- Missing metrics, attribution context, and filters.
If Codex omits this context, ask it to complete the report before acting on any recommendation.
Troubleshooting in the fastest order
Meta Ads is missing from the MCP list
Return to Settings → MCP servers, confirm that the server is saved and enabled, check the URL for spaces, and select Restart. The MCP endpoint is https://mcp.facebook.com/ads; an Ads Manager webpage URL will not work here.
Authenticate keeps returning to the login page
Sign in to Facebook in your default browser first, then retry authentication. Check whether the browser is blocking pop-ups, third-party sign-in, or the local callback. If it still fails, remove the server from Codex and add it again with the URL above.
The account list is empty
This is usually a Meta permissions issue, not a prompt issue. Confirm that the Facebook user in the OAuth flow is the same user who can open the account in Ads Manager. Ask the Business Portfolio administrator to check the account's people assignments.
The account is visible but the query is denied
The user may only have access to some assets or may lack permission to view performance. Confirm the exact ad account ID before reauthorizing so you do not broaden access for the wrong account.
The query succeeds but returns no data
Reduce the range to the last three complete calendar days and confirm that the account actually spent money in that period. Ask Codex to show the filters it used and distinguish zero spend from an unavailable metric.
The report does not match Ads Manager
Compare the account time zone, date boundaries, attribution window, conversion event, currency, and aggregation level. Do not compare a UI report that includes today with the complete-day report in this tutorial.
Credential and execution safety
- Never paste a Facebook password, cookie, OAuth token, or personal access token into a prompt.
- Do not expose full account IDs, client names, or business data in public screenshots.
- Keep the first workflow read-only. Budget, status, bid, and targeting changes belong in a separate approval process.
- Reject a write-tool request and inspect it first. This tutorial requires no write operation.
Official references
- OpenAI: Connect MCP servers to Codex
- OpenAI: Install and start using the desktop app
- Meta: Meta Ads AI Connectors open beta announcement
You now have a reusable, read-only Meta Ads analysis connection. Future requests only need a clear ad account ID, date range, metric list, and an instruction not to change anything; you do not need to configure the server again.