IntroductionGetting started

Codex CLI

Codex CLI connects to the MCP server over HTTP. It does not use mcp-remote. Both OAuth and API key authentication are supported.

Requirements

  • Codex CLI installed and signed in.
  • The codex mcp add command with the --url option. Run codex mcp add --help to confirm. Update Codex CLI if the option is missing.
  • An Ada dashboard account. Available tools depend on your role. See Permissions.

  1. Run this command. Replace acme-corp.ada.support with your Ada instance domain:

    codex mcp add ada --url https://acme-corp.ada.support/api/mcp/oauth

  2. Codex CLI detects OAuth support and opens a browser window. Log in with your Ada credentials.

  3. If the browser window does not open, run:

    codex mcp login ada

  4. Run codex mcp list. Confirm that ada shows OAuth in the Auth column.

  5. Start a new Codex CLI session to load the tools.

Pass the URL with the --url option. If you omit --url, Codex CLI registers the URL as a local command. The command reports success, but the connection fails.

Option 2: API key

API key authentication uses a token generated from your Ada dashboard. Use it for automated setups or when browser-based login is not available.

Codex CLI reads the key from an environment variable when it starts. The key is not written to the configuration file.

  1. Generate an API key from Config > PLATFORM > API keys in your Ada dashboard.

  2. Set the API key as an environment variable in the shell that launches Codex CLI:

    export ADA_API_KEY=your_api_key_here

  3. Run this command. Replace acme-corp.ada.support with your Ada instance domain:

    codex mcp add ada --url https://acme-corp.ada.support/api/mcp --bearer-token-env-var ADA_API_KEY

  4. Run codex mcp list. Confirm that ada shows Bearer token in the Auth column.

  5. Start a new Codex CLI session to load the tools.

Configuration file

Both commands write to ~/.codex/config.toml. The connection applies to every project. You can also edit the file directly:

[mcp_servers.ada]
url = "https://acme-corp.ada.support/api/mcp/oauth"

For API key authentication, use the /api/mcp URL and add bearer_token_env_var = "ADA_API_KEY".

Next steps