Skip to main content

Codex

You need a personal access token — create one in Profile -> API Tokens (guide) — and a current Codex version. Streamable HTTP is a first-class transport in current Codex; no flags needed. Very old builds may require experimental_use_rmcp_client = true — see If the connection fails.

Codex cloud/web doesn't support custom MCP servers. This guide covers the CLI and the IDE extension only.

Quick setup​

Keep the token out of the config file by passing it through an environment variable:

# Add the export to ~/.zshrc or ~/.bashrc so it survives new shells
export WRITEMARS_PAT="writemars_pat_..."

codex mcp add writemars --url "https://api.writemars.com/mcp/" --bearer-token-env-var WRITEMARS_PAT

This works because WriteMars accepts Authorization: Bearer writemars_pat_... alongside X-API-Key.

Verify:

codex mcp list        # writemars should show as connected
codex mcp get writemars   # full details for one server

There is no --header flag on codex mcp add. If you want a custom header instead of the bearer token, edit config.toml directly (below).

config.toml​

codex mcp add writes the global ~/.codex/config.toml. You can edit it by hand — or use .codex/config.toml inside a trusted project. The equivalent of the command above:

[mcp_servers.writemars]
url = "https://api.writemars.com/mcp/"
bearer_token_env_var = "WRITEMARS_PAT"

To send the X-API-Key header instead:

[mcp_servers.writemars]
url = "https://api.writemars.com/mcp/"
env_http_headers = { "X-API-Key" = "WRITEMARS_PAT" }   # value read from the env var

# or static — token sits in the file in plaintext:
# http_headers = { "X-API-Key" = "writemars_pat_..." }

config.toml has no ${VAR} interpolation — bearer_token_env_var and env_http_headers are the only ways to pull values from the environment.

Optional per-server keys: startup_timeout_sec (default 10), tool_timeout_sec (default 60), enabled_tools / disabled_tools to filter tools, and enabled = false to switch the server off without deleting it.

IDE extension​

The Codex IDE extension reads the same ~/.codex/config.toml as the CLI — configure once, both pick it up.

One caveat: an editor launched from the GUI (Dock, Spotlight) may not see env vars set in your shell profile, so bearer_token_env_var and env_http_headers resolve empty. Either launch the editor from a terminal (code .) or use the static http_headers form.

If the connection fails​

Very old Codex builds need a flag for Streamable HTTP:

# ~/.codex/config.toml — old builds only; removed in current Codex
experimental_use_rmcp_client = true

If native HTTP still fails, bridge through mcp-remote over stdio (needs Node.js):

[mcp_servers.writemars]
command = "npx"
args = ["-y", "mcp-remote", "https://api.writemars.com/mcp/", "--header", "X-API-Key:${WRITEMARS_PAT}"]
env = { WRITEMARS_PAT = "writemars_pat_..." }

The X-API-Key:${WRITEMARS_PAT} form (no space after :) sidesteps an argument-splitting quirk in some mcp-remote versions. ${WRITEMARS_PAT} is expanded by mcp-remote itself from its env table — not by Codex's config parser.

More in troubleshooting.

Try it​

Inside any Codex session:

List my WriteMars workspaces.

Then see the tool reference for what's available and the prompt cookbook for example prompts. Connection failing? See troubleshooting.