# Connect Codex.

Source: https://adsuperpowers.ai/docs/setup/codex

Give Codex access to your connected advertising accounts through a remote MCP server.

## Before you begin

Use a current Codex CLI or IDE extension, or Codex in the desktop app, on the host where you want the connection. Local clients on that host share MCP configuration. A remote host needs its own setup; this guide does not configure Codex cloud or a hosted ChatGPT chat.

You need access to Codex, an Ad Superpowers account with an active trial or subscription, and a platform connected in the intended workspace. [Create your account](https://adsuperpowers.ai/signup) or complete the [quickstart](https://adsuperpowers.ai/docs/quickstart) first. Managed devices may restrict which MCP servers you can add.

## 1. Add the server

In a terminal on the same host as Codex, run:

```bash
codex mcp add ad-superpowers --url https://mcp.adsuperpowers.ai/v1
```

This adds a Streamable HTTP connection. If sign-in does not open automatically, run:

```bash
codex mcp login ad-superpowers
```

Sign in to Ad Superpowers in the browser. Review the workspace and requested access before approving. This authorizes the assistant connection; advertising platforms are connected separately in [Integrations](https://adsuperpowers.ai/dashboard/integrations).

## 2. Check the configuration

The default user configuration is `~/.codex/config.toml`. The server entry is:

```toml
[mcp_servers.ad-superpowers]
url = "https://mcp.adsuperpowers.ai/v1"
```

If you edit the file directly, merge this entry with existing settings, then run the login command above. Project configuration in `.codex/config.toml` applies only in trusted projects and can override user settings. Do not add a second server entry if the connection already exists.

## API-key alternative

For a client setup that uses a key, get one from [API Keys](https://adsuperpowers.ai/dashboard/api-keys) for the intended workspace. Make it available as `ADSUPERPOWERS_API_KEY` in the environment of the process that launches Codex, then use this server entry instead of the OAuth-only entry:

```toml
[mcp_servers.ad-superpowers]
url = "https://mcp.adsuperpowers.ai/v1"
bearer_token_env_var = "ADSUPERPOWERS_API_KEY"
```

The variable's name goes in the file; its secret value does not. Set the value through your host's private environment or secret manager, then restart Codex. A variable exported in a terminal is not automatically available to an already-running desktop or IDE process. Do not paste a key into the conversation.

## 3. Verify a read result

Start a new Codex conversation. In the CLI, use `/mcp` to inspect the server, or run `codex mcp list` in the terminal. Then ask:

```text
Use Ad Superpowers skill(action="connection_health") to check my
platform connections. Then list the advertising accounts I can access.
Do not change anything.
```

A healthy connection is only the first check. Confirm the expected account name and ID, then ask:

```text
For [account name and ID], show campaign spend and conversions
for the last 7 days. Include the date range and currency.
Do not change any campaigns.
```

Confirm the account, dates and currency against the advertising platform. An empty result is not proof of successful reporting unless the account and period are correct.

## If it does not connect

| What you see | Next check |
| --- | --- |
| Server missing | Check the host and active user/project configuration; restart Codex. |
| Sign-in required or expired | Run `codex mcp login ad-superpowers`, complete authorization, then start a new conversation. |
| API-key authentication fails | Check that the launching process receives the named variable and that the key is valid in the intended workspace. |
| Tools unavailable on a managed device | Ask your administrator whether this MCP server and its tools are allowed. |
| Connected, but an account is missing | Check the workspace and platform connection in Integrations, then repeat the read check. |

Switching workspaces in the dashboard alone does not move an existing assistant connection. Reauthorize for the intended workspace or configure its key. For further help, use [troubleshooting](https://adsuperpowers.ai/docs/troubleshooting).

## Next steps

Follow the [example prompts](https://adsuperpowers.ai/docs/examples). Client configuration was checked against [OpenAI's MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) and [Codex's CLI implementation](https://github.com/openai/codex/blob/main/codex-rs/cli/src/mcp_cmd.rs) on 18 September 2026. This guide does not promise a fixed login lifetime; reconnect if the client requests it.