> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://support.promo.ly/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Connect Codex

These steps connect the Codex CLI to your Promoly account. Last tested on **October 2, 2026** with Codex CLI 0.159.0.

Connected agents are in an invite-only beta. See [Connect an AI coding agent](https://support.promo.ly/en/article/connect-an-ai-coding-agent-1udge2h/) for what an agent can and can't do.

## Add the Promoly server

Open `~/.codex/config.toml` and add:

```toml
[mcp_servers.promoly]
url = "https://api.promo.ly/mcp"

[mcp_servers.promoly.oauth]
client_id = "promoly-codex"
callback_port = 18431
callback_url = "http://127.0.0.1/callback"
```

Keep all three `oauth` lines. Promoly only accepts this client ID with this exact callback, and Codex uses a different callback when one of them is missing.

## Sign in

```sh
codex mcp login promoly
```

Your browser opens Promoly. Sign in, choose the account, decide whether to allow drafts, and click **Allow access**. The terminal shows `Successfully logged in to MCP server 'promoly'`.

## Check the connection

Start Codex and paste:

```text
Use the promoly tools to show which Promoly account you're connected to, then list my five most recent campaigns.
```

## Sign out or remove it

```sh
codex mcp logout promoly
```

Then delete the `promoly` sections from `config.toml` if you want to remove the server. Signing out on your computer doesn't end the connection on Promoly's side. To do that, disconnect it under **Profile** → **Manage connected apps** in the dashboard.

## If something goes wrong

- **Port 18431 is busy.** Another app is using it. Close that app and run `codex mcp login promoly` again.
- **Codex says the promoly tools aren't available after you disconnected or reconnected.** Start a new Codex session. A session that was already open when the connection changed doesn't pick up the new sign-in.
- **The browser shows an error about the redirect address.** Check that `callback_port` and `callback_url` match the lines above exactly.
- **You're on a remote machine over SSH.** `codex mcp login promoly --no-browser` prints the sign-in link. Open it on any computer, then paste the address the browser lands on back into the terminal.