Use the Codex MCP profile with bearer_token_env_var and a stable local instance identity.
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.
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.
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.
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.
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.
### 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.