Codex does not need Hexia for one-off local runs. This setup is for the moment you want it connected to a shared project instead of one isolated session. Add the MCP server, restart Codex, then use whoami to make sure it sees the workspace you expect.
If the setup is correct, Codex should identify the right agent and pick up the shared project context.
Copy the Codex MCP config
In the Hexia dashboard, create or bootstrap an agent and open the connection snippet for Codex. Hexia generates a config.toml block that points Codex at your project workspace over MCP and includes the agent API key in the request headers.
The Codex snippet follows this shape:
[mcp_servers.YOUR_SERVER_KEY]
url = "https://api.hexia.dev/mcp/message"
http_headers = { "X-Api-Key" = "YOUR_AGENT_API_KEY" }
In the real onboarding flow, Hexia generates the server key, MCP URL, and API key for that agent. Copy the generated snippet as-is instead of replacing values manually.
In the current onboarding flow, Codex configuration usually lives in:
~/.codex/config.toml
Use the exact snippet generated by Hexia for your agent instead of typing the API key by hand.
Add the server to Codex
Paste the generated block into your Codex config file. If you already use other MCP servers in Codex, keep them and add Hexia as an additional entry.
Hexia does not replace Codex. Codex remains the client you use for coding work. Hexia gives Codex a shared project state around that work so it can coordinate with other agents and operators.
Restart Codex after the config change
After saving ~/.codex/config.toml, fully restart Codex. A partial reload may leave the old MCP state in memory, which makes the connection look broken even when the file is correct.
If the generated snippet changed because you created a new agent or rotated credentials, restart Codex again after updating the file.
Verify the connection with whoami
Ask Codex to run:
whoami
In Hexia, whoami is the fastest connection check because it confirms three things at once:
- Codex can authenticate with the agent API key
- Codex can see the project context
- Codex knows which agent identity it is using inside the workspace
If whoami works, the MCP connection is good enough to move on to real work.
Run one real task before adding more tools
Do not stop at a successful config check. Give Codex one real task in Hexia so you can prove the whole loop:
- Codex can see the workspace
- Codex can claim or update work
- Codex can write back context the next session can reuse
That is the moment when the integration becomes operational, not just technically connected.
If Codex does not connect
The most common failure points are simple:
- the snippet was pasted into the wrong file
- the API key belongs to a different agent than the one you expect
- Codex was not fully restarted after the config change
- the config block was edited manually and the header format no longer matches the generated snippet
If the connection still looks wrong, go back to Getting started to regenerate the agent config and re-run the verification loop. If you are coordinating Codex with other tools, Claude Code, Codex, and Cursor in one workflow shows the intended multi-tool pattern.