Codex

Codex, OpenAI's coding agent, connects to Workstate's two MCP servers over Streamable HTTP. You add the servers to Codex's config.toml file, and Codex reads your key from an environment variable.

What you need

• A Workstate API key. See API keys.
• Your namespace id, such as ws-…. It is on the console's Namespaces page, and in the configuration under Connect your agent on the API keys page.
• The Codex CLI.

Connect Codex

1. Set your key as the RAG_API_KEY environment variable, in the terminal where you run Codex:

   export RAG_API_KEY='rgc_live_…'

   To set it in every new terminal, add that line to your shell profile, such as ~/.zshrc, but only if that file is not kept in a Git repository.

2. Open ~/.codex/config.toml, or create it, and add both servers. Replace ws-… with your namespace id:

   [mcp_servers.rag-corpus]
   url = "https://mcp-uat.workstate.io/corpus"
   bearer_token_env_var = "RAG_API_KEY"
   http_headers = { "X-RAG-Namespace" = "ws-…" }
   
   [mcp_servers.rag-ledger]
   url = "https://mcp-uat.workstate.io/ledger"
   bearer_token_env_var = "RAG_API_KEY"
   http_headers = { "X-RAG-Namespace" = "ws-…" }

   bearer_token_env_var names the environment variable that holds your key. http_headers adds the namespace header to every request. Name the servers rag-corpus and rag-ledger, the names your agent instructions use. See Server names.

3. Start Codex from the terminal where RAG_API_KEY is set.

To connect Workstate to one project only, put the same lines in .codex/config.toml in the project's folder instead. Codex reads a project's configuration only when you trust the project.

Or use the command line

codex mcp add can add the servers for you:

codex mcp add rag-corpus --url https://mcp-uat.workstate.io/corpus --bearer-token-env-var RAG_API_KEY
codex mcp add rag-ledger --url https://mcp-uat.workstate.io/ledger --bearer-token-env-var RAG_API_KEY

The command has no option for other headers. Afterwards, add the http_headers line to each server in ~/.codex/config.toml, as in step 2. Without that header, Codex reaches your oldest namespace.

Check it worked

1. Run codex mcp list. It lists rag-corpus and rag-ledger.

2. In Codex, run /mcp to see the active servers.

3. Ask a question that your sources can answer, and ask for citations. For example:

   Use search_corpus to find where we set the retry limit for outgoing emails.
   Cite the repository, file and lines for each result.

4. On API keys, the key's Last used time updates.

Give Codex the instructions

Codex reads AGENTS.md files. Paste the text from Agent instructions into ~/.codex/AGENTS.md for all your projects, or into AGENTS.md at the root of a repository for everyone who works on it.

Troubleshooting

What you see	Likely cause	What to do
Calls fail with 401: missing bearer token or invalid or revoked key	Codex started without RAG_API_KEY, or the key was revoked or copied incompletely.	Set the variable in the terminal and start Codex again. If the key was revoked or lost, create a new one.
The servers in .codex/config.toml are missing	Codex reads a project's configuration only in a trusted project.	Trust the project in Codex, or move the servers to ~/.codex/config.toml.
no grant for namespace "ws-…"	The X-RAG-Namespace header names a namespace you do not have access to.	Use a namespace id from the Namespaces page.
principal has no workspace grants	You have not been given a namespace yet.	Ask an owner or admin to give you one on the Team page.
Searches return nothing, or not what you expect	The first sync has not finished, or your sources are in another namespace.	Check that the sources show Up to date, and that the namespace id matches the namespace your sources are in.
repo not given and could not be inferred from a git repo	The agent tried to record a ledger topic without naming a project.	Tell it which project to file the topic under.

Related

• Agents & clients
• Agent instructions
• API keys
• MCP tools