essential

Connect SearchAds Manager to Codex

Enable the local MCP server in SearchAds Manager, connect it to Codex, and verify it with a disposable Apple Search Ads smoke test.

Download on the App Store
Back MCP Overview

Use this page when you want Codex to work against Apple Search Ads through the local SearchAds Manager app instead of a custom API script.

1. Set up the macOS app

  1. Launch SearchAds Manager on macOS.
  2. Open Settings.
  3. Configure the normal Apple Search Ads credentials if they are not already set.
  4. Open the Codex MCP Server section.
  5. Enable the server.
  6. Review or change the port and token if needed.
  7. Click Apply Server Settings.

If credentials are not configured yet, follow Apple’s OAuth guide: Implementing OAuth for the Apple Search Ads API.

2. Add the server to Codex

The settings card shows the exact command to run. The command format is:

codex mcp add searchads --url "http://127.0.0.1:7717/mcp?token=YOUR_TOKEN"

After adding it:

  1. Keep the macOS app running.
  2. Start a new Codex session in the repo where you want to work, or reconnect MCP servers if your client supports it.
  3. Use the searchads server for reporting and write operations instead of manual API scripting.
  1. Call list_apps first when you need an adam_id.
  2. Call list_supported_countries before campaign creation when you need valid country codes.
  3. Use get_campaign_report, get_adgroup_report, and get_keyword_report to inspect performance before making changes.
  4. Use list_campaigns, list_adgroups, and list_keywords to inspect current state before making changes.
  5. Use create_campaigns, add_adgroups, and add_keywords for creation flows.
  6. Use update_campaigns, update_adgroups, and update_keywords for controlled edits.
  7. Use delete_campaigns, delete_adgroups, and delete_keywords only for explicit destructive cleanup.
  8. Prefer small, explicit batches for writes so failures are easier to review.

4. Troubleshooting

  1. If Codex cannot connect, confirm the macOS app is open and the server status shows Running.
  2. If tool calls fail with configuration errors, recheck the Apple Search Ads credentials in app settings.
  3. If you regenerate the token or change the port, rerun codex mcp add ... with the new URL.

5. Disposable smoke-test prompts

Run the prompts below in the same Codex session so it can remember the test IDs it creates.

Use a disposable naming prefix such as mcp-smoke-... and delete everything at the end. Fresh test entities usually have zero metrics in reports; that still validates the MCP reporting path.

Discovery prompt

Using only the `searchads` MCP server, prepare an MCP smoke-test setup.1. Find one owned app I can safely use for a disposable test campaign. Prefer an app matching "Monitor and Manage Search Ads"; otherwise list the first 5 owned apps and pick one.2. Call `list_supported_countries` and choose `US` if it is supported. If not, choose one supported country and tell me which code you picked.3. Call `list_campaigns` for any campaigns whose names start with `mcp-smoke-`.4. Tell me the chosen `adam_id`, country code, and a unique test prefix in the form `mcp-smoke-YYYYMMDD-HHMMSS`.5. Do not create anything yet.

Create campaign prompt

Using only the `searchads` MCP server, create one disposable paused test campaign named `<PREFIX>-campaign` for the app and country chosen earlier.Use:- the chosen `adam_id`- one country code- `daily_budget_amount` 5- `currency` `USD`After creation, call `list_campaigns` with the test prefix and return the new `campaign_id`.

Campaign report and update prompt

Using only the `searchads` MCP server:1. Call `get_campaign_report` for `<CAMPAIGN_ID>` with `days: 0`.2. Update that campaign with `update_campaigns` so the daily budget becomes 6 USD and the status becomes `ENABLED`.3. Call `list_campaigns` again for the test prefix.4. Summarize the campaign before and after the update.

Add ad groups prompt

Using only the `searchads` MCP server, add two paused ad groups to `<CAMPAIGN_ID>`:1. `<PREFIX>-ag-1`2. `<PREFIX>-ag-2`Use:- `default_bid_amount` 1- `currency` `USD`- `automated_keywords_opt_in` falseAfter creation, call `list_adgroups` for the campaign and return both `ad_group_id` values.

Ad group report and update prompt

Using only the `searchads` MCP server:1. Call `get_adgroup_report` for `<CAMPAIGN_ID>` with `days: 0`.2. Update `<PREFIX>-ag-1` with `update_adgroups` so it becomes `ENABLED`, its `default_bid_amount` becomes 1.2 USD, and its `cpa_goal_amount` becomes 4 USD.3. Call `list_adgroups` again for `<CAMPAIGN_ID>`.4. Summarize the updated ad group and return its `ad_group_id`.

Add keywords prompt

Using only the `searchads` MCP server, add keywords to `<AD_GROUP_ID>` in `<CAMPAIGN_ID>` using one `keyword_set`.Use:- `default_bid_amount` 0.8- `default_currency` `USD`Add these keywords:1. `<PREFIX> exact` with `match_type` `EXACT` and `status` `ACTIVE`2. `<PREFIX> broad` with `match_type` `BROAD` and `status` `ACTIVE`After creation, call `list_keywords` for `<CAMPAIGN_ID>` and `<AD_GROUP_ID>` and return the created `keyword_id` values.

Keyword report and update prompt

Using only the `searchads` MCP server:1. Call `get_keyword_report` for `<CAMPAIGN_ID>` and `ad_group_ids: [<AD_GROUP_ID>]` with `days: 0`.2. Update the EXACT keyword with `update_keywords` so its bid becomes 0.9 USD and its status becomes `PAUSED`.3. Call `list_keywords` again for `<CAMPAIGN_ID>` and `<AD_GROUP_ID>`.4. Summarize the updated keyword and return both current keyword rows.

Cleanup prompt

Using only the `searchads` MCP server, clean up the MCP smoke test.1. Delete all test keywords in `<AD_GROUP_ID>` with `delete_keywords`.2. Call `list_keywords` for `<CAMPAIGN_ID>` and `<AD_GROUP_ID>` to confirm the keywords are gone.3. Delete both test ad groups with `delete_adgroups`.4. Call `list_adgroups` for `<CAMPAIGN_ID>` to confirm the ad groups are gone.5. Delete the test campaign with `delete_campaigns`.6. Call `list_campaigns` for the test prefix to confirm the campaign is gone.7. Summarize the cleanup results.
© 2026 Remote Sunrise LTD
essential