# Codex

Use the Codex MCP profile with bearer_token_env_var and a stable local instance identity.

- Canonical: https://docs.xmemo.dev/docs/mcp/codex
- Locale: en-US
- Content-Locale: en-US
- Canonical-Content-Digest: 7098666a645b296cf4f818dbf7fc006dcd1102bdf89a0e0e87be91981a8f4651
- Edition-Digest: 2ee111b97fa1b57623cea09bd1d2a4a214f91a00ec9ad8478e5e12f34999013d
- Source-Revision: sha256:c1d63ff2e9d2e3ed6bd0a427abb152e5ff001e767461909c8533068fc6a42ec6

## Prerequisite

Use a Codex MCP profile that supports hosted Streamable HTTP, bearer_token_env_var, and non-secret HTTP identity headers.

- Endpoint: https://xmemo.dev/mcp.
- Auth mode: direct MCP with bearer_token_env_var.
- Config file: ~/.codex/config.toml.

## Install / setup

Use the XMemo client command to write the reviewed Codex profile instead of hand-editing the TOML.

```bash
npx @xmemo/client mcp add codex --write
```

## Set the credential

Set XMEMO_KEY in the environment used to launch Codex. bearer_token_env_var reads the value without putting the token in config.toml.

```bash
export XMEMO_KEY='<your-xmemo-token>'
```

## Generate / confirm XMEMO_AGENT_INSTANCE_ID

The reviewed client command generates the stable instance mapping for this install. Confirm that env_http_headers maps XMEMO_AGENT_INSTANCE_ID and keep the same non-secret value on later runs.

```bash
export XMEMO_AGENT_INSTANCE_ID='<stable-local-instance-id>'
# Persist and reuse this value for the same local install
```

## Preserve the existing config block

Use the existing Codex XMemo configuration block rendered on this page. Preserve bearer_token_env_var, env_http_headers, and the XMemo URL; do not paste the token into config.toml.

## Restart the client

Restart Codex after writing the profile or changing XMEMO_KEY so the new environment and MCP server definition are loaded.

## Test with a real recall call

Make the first MCP call read-only. This is an actual recall invocation, not a health-check placeholder, and it does not write memory.

```text
recall({ query: "connection check", limit: 1 })
```

## Expected response (literal shape)

A successful call returns the public ranked text shape below; the reference and content are real values from the authorized memory space.

```text
### XMemo Memory Results:
1. Reference: <opaque-memory-id> | Location: <location>
   > <memory content>
```

## Common Errors

Codex direct MCP failures use the bearer_token_env_var path and its shared authorization contract.

- 401 invalid_token — XMEMO_KEY is missing, expired, revoked, or otherwise invalid: verify the environment seen by Codex and restart.
- 403 insufficient_scope — the token does not grant memory:read: issue a token with the required scope.
- Invalid XMEMO_AGENT_INSTANCE_ID values are normalized to no instance attribution rather than raising an auth error: regenerate a stable value using allowed characters and persist it.

## Verify before writing

The real recall check above is read-only; do not proceed to a write until its response and attribution are understood.

## Codex

Direct client: Codex reads XMEMO_KEY through bearer_token_env_var and sends non-secret identity headers. Run npx @xmemo/client mcp add codex --write to generate the stable XMEMO_AGENT_INSTANCE_ID automatically.

```
[mcp_servers.XMemo]
url = "https://xmemo.dev/mcp"
bearer_token_env_var = "XMEMO_KEY"

[mcp_servers.XMemo.http_headers]
X-Memory-OS-Agent-ID = "codex"
X-Memory-OS-Agent-Instance-ID = "${XMEMO_AGENT_INSTANCE_ID}"

```