How Do I Connect Codex to WaveBrain?
Connect Codex to WaveBrain for MCP logging: add the server with codex mcp add, set WAVEBRAIN_API_KEY, test it in /mcp, and fix the usual setup problems.
Reviewed by WaveBrain Operations TeamReviewed 5 min readPublished
The short answer
To connect Codex to WaveBrain, run codex mcp add wavebrain --url https://getwavebrain.com/api/mcp --bearer-token-env-var WAVEBRAIN_API_KEY, then export WAVEBRAIN_API_KEY with your key in your shell profile and open a new terminal. Start codex, check /mcp, ask it to log a test action, and the entry shows up on your WaveBrain timeline.
Codex is good at long, unattended runs, which is exactly when you lose track of what it did. You come back to a finished task and a summary, but the summary does not say which of the four things it pushed went to production. Connecting Codex to WaveBrain gives every outside action a line on a timeline you can check from anywhere.
Codex supports remote MCP servers with bearer tokens, so the setup is one command, one environment variable and a quick test. This guide covers each step, how to confirm it works, and what to check when it doesn't.
What do you need before you start?#
You need the Codex CLI, a WaveBrain account and a WaveBrain API key. WaveBrain's free plan includes 1,000 actions a month, 7-day history and 2 API keys, and it needs no credit card.
WaveBrain runs as a hosted MCP server at https://getwavebrain.com/api/mcp over Streamable HTTP with a bearer token. OpenAI's Codex MCP docs list Streamable HTTP servers and bearer token authentication among the supported features, so no local bridge is required.
How do you connect Codex to WaveBrain step by step?#
You connect Codex to WaveBrain by registering it as a Streamable HTTP MCP server that reads your key from an environment variable. It takes about two minutes.
- Create a free WaveBrain account, open the Setup page in the dashboard and pick Codex.
- Create an API key and copy it. The page shows it only once.
- Add the server to Codex.
codex mcp add wavebrain --url https://getwavebrain.com/api/mcp --bearer-token-env-var WAVEBRAIN_API_KEY
- Put the key in your shell profile (
~/.zshrcor~/.bashrc).
export WAVEBRAIN_API_KEY="<YOUR_API_KEY>"
- Open a new terminal so the variable is set, then start
codex. - Optional, for consistent logging. Paste WaveBrain's logging rules from the Setup page into
~/.codex/AGENTS.md. OpenAI's AGENTS.md guide says Codex reads AGENTS.md files before doing any work, and the file in your Codex home directory applies to every repository.
Step 3 writes an [mcp_servers.wavebrain] table to ~/.codex/config.toml. The Codex CLI reference describes --url as registering a Streamable HTTP server instead of stdio, and --bearer-token-env-var as the environment variable "whose value is sent as a bearer token". Your key never goes into the config file itself.
Is there a Codex plugin instead?#
Yes, WaveBrain has an open source Codex plugin that adds the MCP server, a skill that tells Codex when to log, and auto-capture hooks. It installs with two commands.
codex plugin marketplace add tambo-ai-labs/wavebrain
codex plugin add wavebrain@wavebrain
The plugin also reads the key from WAVEBRAIN_API_KEY, so step 4 still applies. Codex's hooks docs say non-managed hooks must be reviewed and trusted before they run, so start codex, open /hooks and trust the two WaveBrain hooks once. After that, high-stakes tool calls such as deploys, pushes and merges are queued locally, redacted for secrets and sent at the end of each turn, and duplicates of actions Codex logged itself are dropped. Pick the plugin or the codex mcp add command, not both.
How do you confirm Codex is connected?#
You confirm the connection by checking the server list, then logging one test action and finding it on your WaveBrain timeline. OpenAI's docs give two ways to check the list.
- In a terminal, run
codex mcp list. You should seewavebrainwith its URL. - Inside the Codex TUI, type
/mcpto see your active MCP servers.
Next, ask Codex something like "Log a test action to WaveBrain titled Connected Codex to WaveBrain, type other, project test." Codex calls the log_action tool and the entry appears at the top of your activity timeline within seconds. Agent names are stored in lowercase, so expect something like codex.
Then try a real task with an outside effect, such as opening a pull request. WaveBrain's server instructions tell agents to log anything with external effects (deploys, pushes, posts, emails, config changes) right after it happens without being asked, and to skip pure reads. A task that only reads files will not create an entry, which is expected.
Why isn't Codex logging to WaveBrain?#
Most Codex setup problems come down to the environment variable not reaching Codex. Check these in order.
- The variable isn't set.
--bearer-token-env-vartakes the name of a variable, not the key. Runecho $WAVEBRAIN_API_KEYin the terminal where you start Codex. If it prints nothing, add the export line to the right profile file and open a new terminal. - The server connects but calls fail with an authentication error. WaveBrain returns 401 for an invalid key. Create a new key, update the export line and open a new terminal.
- The server is missing from
codex mcp list. Run the add command again. OpenAI's docs say project-level.codex/config.tomlfiles only load in trusted projects, so the user-level config is the safer place. - Codex finishes tasks without logging. Add the logging rules to
~/.codex/AGENTS.mdand check that the task had an outside effect. - Plugin hooks don't fire. Open
/hooksand trust the WaveBrain hooks. - Logging stops mid-month. The free plan rejects new actions after 1,000 in a month and resumes the next month, and your history is kept.
If WaveBrain is unreachable, Codex keeps working. The log_action call returns an error, the task continues, and plugin hook entries wait in the local queue.
What does WaveBrain record from Codex?#
WaveBrain records only what Codex reports and what plugin hooks capture. Each entry has a title, details, project, link, status and optional metadata. It never reads your repository or files, never receives prompts, responses or conversations, stores API keys as hashes and keeps data in the United States.
Text Codex writes into an entry is not filtered for secrets on the server, so treat entries like commit messages. WaveBrain is not a tracing tool either, so there are no token counts or latency numbers. To compare WaveBrain with Codex's session history, OpenTelemetry export and hooks, see the best ways to track Codex agent activity. Codex's MCP docs note that the ChatGPT desktop app, Codex CLI and IDE extension share the same MCP configuration, and WaveBrain puts Codex on the same timeline as your other agents. To add Claude Code next, follow how to connect Claude Code to WaveBrain, or see which agents WaveBrain supports.
Frequently asked questions#
Where does Codex store the WaveBrain MCP server?#
codex mcp add writes the server to ~/.codex/config.toml as an [mcp_servers.wavebrain] table with the URL and the name of the variable that holds your key.
Does Codex support remote MCP servers with an API key?#
Yes. OpenAI's Codex docs list Streamable HTTP servers with bearer token authentication, and --bearer-token-env-var sends a variable's value as the bearer token.
Why use an environment variable instead of pasting the key?#
The config file stores only the variable name, so the key stays out of config.toml and out of any dotfiles you sync or share.
Can Codex and Claude Code log to the same WaveBrain account?#
Yes. Connect each agent with a key from the same workspace and their actions land on one timeline, filterable by agent and project.
How do I remove WaveBrain from Codex?#
Run codex mcp remove wavebrain, or remove the plugin if you installed it. You can also delete the API key in the WaveBrain dashboard.