# Codex MCP (Manual)

> Manually connect the OpenAI Codex CLI to xmemory through MCP.

Canonical page: https://xmemory.ai/codex/

This guide shows how to connect the [OpenAI Codex CLI](https://developers.openai.com/codex/) 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.

:::note[There is also a Codex plugin]
Codex can install the same xmemory plugin package as Claude Code, which brings the skills and the
session-start hook rather than the MCP server alone — see
[Agent-guided setup](https://xmemory.ai/install/#codex). This page covers the headless path, where Codex
authenticates with an API key instead of a browser sign-in.
:::

---

## Prerequisites

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

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

Get a key from the [xmemory Console](https://console.xmemory.ai) and the UUID of an instance it can access. If you need an instance, describe what your agent should remember and create it with the [CLI](https://xmemory.ai/cli/#onboard-create-an-instance-from-a-description) or [Python SDK](https://xmemory.ai/python/#quick-start). Use the returned UUID in the MCP 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).

Name the table `xmemory-` plus the **first eight characters of the instance id** — the same name
`xmemcli instance setup` prints for it. One table is one connection to one instance, so a second
instance under a shared name replaces the first, and the plugin already ships a server called
`xmemory` pointing at the shared host.

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](https://xmemory.ai/mcp/#authentication) for the other connection options.

```toml
[mcp_servers.xmemory-<FIRST8>]
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 `):

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

```bash
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`:

```bash
codex mcp add xmemory-<FIRST8> \
  --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 `401`s, 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 10 default tools — 7 bound (`get_instance_id`, `get_instance_schema`, `get_setup_instructions`, `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](https://xmemory.ai/mcp/#tools) reference for full parameter and return-shape details.
