Codex

This guide shows how to connect the OpenAI Codex CLI to xmemory via MCP. Codex talks to the xmemory MCP server over Streamable HTTP and gets write and read (and more) as ready-made tools — no custom code.

API key: To use xmemory APIs or integrations, you need an API key. Get one from the xmemory console. Copy and securely store the key. Never share your API key publicly.

---

Prerequisites

Install the Codex CLI (remote MCP servers with custom headers need Codex 0.46+; use a current build):

npm install -g @openai/codex
codex --version

You also need an xmemory instance ID. The fastest way to create one is the CLI (xmemcli xmd generate → validate → instance create); the Python guide works too. Keep the returned UUID — you’ll put it in the server URL below.

---

Configure the MCP server

Codex reads MCP servers from ~/.codex/config.toml. Add an [mcp_servers.<name>] table. Because the server is remote, set url; the transport is detected automatically (Streamable HTTP).

This headless flow sends your account API key directly as the Bearer token on the /instance/<instance_id> shortcut path — no OAuth exchange needed. The instance is bound by the URL path. See the MCP guide for the other connection options.

[mcp_servers.xmemory]
url = "https://mcp.xmemory.ai/instance/<INSTANCE_ID>"
http_headers = { Authorization = "Bearer <your-xmemory-api-key>" }

http_headers values are sent verbatim on every request — include the Bearer prefix yourself.

Keep the token out of the file

To avoid storing the key in config.toml, use env_http_headers, which reads each header value from an environment variable (the variable holds the full header value, including Bearer ):

[mcp_servers.xmemory]
url = "https://mcp.xmemory.ai/instance/<INSTANCE_ID>"
env_http_headers = { Authorization = "XMEM_AUTH_HEADER" }

export XMEM_AUTH_HEADER="Bearer your-xmemory-api-key"

Adding it from the command line

codex mcp add can register a remote server, but it cannot write custom headers — it only sets bearer_token_env_var:

codex mcp add xmemory \
  --url "https://mcp.xmemory.ai/instance/<INSTANCE_ID>" \
  --bearer-token-env-var XMEM_API_KEY

Note: bearer_token_env_var attaches the token to request POSTs but not to the SSE GET stream, which can return 401 against servers that authenticate every request (xmemory does). If you see 401s, use the http_headers / env_http_headers form above instead — those are sent on every request.

---

Available MCP tools (instance connection type)

The instance connection exposes 9 default tools — 6 bound (get_instance_id, get_instance_schema, write, write_async, write_status, read) and the 3-tool schema-evolution suggestion engine (review_suggestions, decide_suggestions, apply_pending_decisions) — plus an opt-in Schema management group (5 more). See the MCP — Tools reference for full parameter and return-shape details.