Guides

How to set up an MCP server in Codex

Connect OpenAI's Codex CLI to a remote MCP server with one command, finish OAuth sign-in, and manage servers in config.toml.

4 min read

Codex reaches tools outside your terminal through the Model Context Protocol (MCP). Add a server once and its tools are available in every Codex session, in the CLI and the IDE extension alike, since both read the same config.

This guide uses the OutcomeCI MCP server as the running example. The same steps work for any remote MCP server; swap in its name and URL.

What you need

  • The Codex CLI installed. Check with codex --version.
  • The server's URL, and an account with the service behind it.
  • For OutcomeCI, an OutcomeCI account with access to a workspace.

Add a remote server

Run codex mcp add with a name and --url:

codex mcp add outcomeci --url https://api.outcomeci.com/v1/mcp

--url tells Codex this is a remote server it connects to over streamable HTTP, rather than a local command it starts. The name is yours to choose; it is how the server appears in codex mcp list and in tool names.

When the server supports OAuth, Codex detects it and starts sign-in straight away:

Added global MCP server 'outcomeci'.
Detected OAuth support. Starting OAuth flow…

Sign in

Your browser opens the provider's sign-in page. For OutcomeCI:

  1. Sign in to OutcomeCI if prompted.
  2. Select the workspace you want Codex to help configure.
  3. Review the requested access and select Allow access.
  4. Return to your terminal.

If you closed the browser or the flow timed out, start it again at any time:

codex mcp login outcomeci

On a machine without a browser, such as a remote dev box over SSH, add --no-browser. Codex prints the authorization URL; open it on any machine, then paste the callback URL back into the terminal.

To sign out, run codex mcp logout outcomeci.

Check the connection

codex mcp list

The server should show as enabled. Its Auth column reads Not logged in until sign-in completes. For one server's full settings:

codex mcp get outcomeci

Inside a Codex session, /mcp lists the connected servers and their tools.

Where the config lives

codex mcp add writes to ~/.codex/config.toml, or to config.toml under $CODEX_HOME when that is set. The entry is plain TOML, so you can also write it by hand:

[mcp_servers.outcomeci]
url = "https://api.outcomeci.com/v1/mcp"

The file holds no credentials. Codex keeps OAuth tokens separately and refreshes them as needed, so the config is safe to keep in your dotfiles.

Servers that take an API key

Some remote servers authenticate with a static token instead of OAuth. Keep the token in an environment variable and tell Codex its name:

export EXAMPLE_MCP_TOKEN=your-token
codex mcp add example --url https://mcp.example.com/mcp \
  --bearer-token-env-var EXAMPLE_MCP_TOKEN

Codex reads the variable when it connects and sends it as a bearer token. The token itself never lands in config.toml.

Add a local server

For a server that runs on your machine, put the command after --, and pass environment variables with --env:

codex mcp add my-server --env API_KEY=your-key -- npx -y my-mcp-server

Put it to work

With the OutcomeCI server connected, describe the workflow you want and let Codex build it with you:

Help me create an OutcomeCI workflow that runs every weekday at 9am, reads the open pull requests in our repository, and posts a summary of the ones waiting on review to Slack. Show me the workflow before publishing it.

Codex can read the workflow format, inspect your existing workflows, and create or update them within the access you approved. When a workflow needs a credential, OutcomeCI gives you a browser form for it, so the value goes into your Vault and never passes through the conversation.

Run your workflows with Codex

This guide connects Codex to OutcomeCI so it can build workflows with you. To have OutcomeCI run those workflows with Codex on your ChatGPT subscription, see Run OutcomeCI workflows with Codex.

Troubleshooting

Sign-in fails right away. Confirm the URL is complete. For OutcomeCI it ends in /v1/mcp. Then run codex mcp login outcomeci again.

The browser opens, but Codex never hears back. The callback goes to a port on 127.0.0.1, which a remote or containerized session cannot receive. Use codex mcp login outcomeci --no-browser and paste the callback URL instead.

You picked the wrong workspace. Run codex mcp logout outcomeci, then sign in again and choose the right one.

The server needs to go. Run codex mcp remove outcomeci.

Next steps