Codex CLI

TOML config or a GUI form — for both the local server and the cloud endpoint.

local stdio
cloud API key
verified

Codex supports a local stdio server via TOML config (or a CLI one-liner), and the cloud endpoint via a Streamable HTTP GUI entry.

Local (stdio)

Codex uses TOML, not JSON — default path ~/.codex/config.toml (or .codex/config.toml per trusted project). command runs uvx, which downloads and runs Spomory on demand — no install step:

[mcp_servers.Spomory]
command = "uvx"
args = ["--from", "spomory[llm,embedding,mcp]", "spomory-mcp"]

[mcp_servers.Spomory.env]
LLM_API_KEY = "..."
LLM_BASE_URL = "https://api.deepseek.com"
LLM_MODEL = "deepseek-v4-flash"

Or add it without editing the file: codex mcp add Spomory --env LLM_API_KEY=... --env LLM_BASE_URL=https://api.deepseek.com --env LLM_MODEL=deepseek-v4-flash -- uvx --from spomory[llm,embedding,mcp] spomory-mcp.

Codex's desktop/IDE builds also have a GUI entry point: Plugins → Manage → MCPs → "+ Add server", type STDIO.

Both the config file and the GUI path are verified against a real Codex installation.

Prefer a fixed, pinned install over uvx's on-demand cache? Install into a virtual environment outside ~/Documents (pip install 'spomory[llm,embedding,mcp]'), then point command at that venv's bin/memory-core-mcp directly.

Where do these environment variables come from?

LLM_API_KEY is your key for whichever OpenAI-compatible provider you use for extraction — OpenAI, DeepSeek, Qwen, and others all work. LLM_BASE_URL and LLM_MODEL default to OpenAI if you leave them out; swap them to point at DeepSeek, Qwen, or any other OpenAI-compatible provider, or a fully local server (Ollama, vLLM, llama.cpp, MLX):

export LLM_API_KEY=...
export LLM_BASE_URL=https://api.deepseek.com   # optional, defaults to OpenAI
export LLM_MODEL=deepseek-v4-flash             # optional, defaults to gpt-4o-mini
export EMBEDDING_MODEL=BAAI/bge-m3             # optional, defaults to bge-m3

Full local setup guide, including the macOS ~/Documents gotcha →

Full local setup guide on GitHub →

Cloud (API key)

Also uses the API key. Codex's desktop/IDE builds have a GUI entry point: Plugins → Manage → MCPs → "+ Add server", type Streamable HTTP, URL https://api.yliuai.com/mcp-apikey/, header x-api-key: <your key>.

Verified against a real Codex installation, connecting and listing tools correctly over the real remote endpoint.

Where does <your key> come from?

Get one instantly with curl — fine for your own testing:

curl -X POST https://api.yliuai.com/users/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'
# the api_key in the response (starts with mck_) is shown only this once -- save it

That hands you a key with no proof you control the email — fine for testing, but for real use, get one through the email-confirmation form instead, which actually verifies the address.

Get a verified key on the Cloud & Apps page →

Full remote-access guide on GitHub →

Make it actually get used

Connecting the tools doesn't mean your client reaches for them on its own — it needs to be told to call search_memory before answering and add_memory after you share something worth keeping. SKILL.md is a short instructions file that does that. How you load it is specific to each client: some auto-discover a skills folder the same way Claude Code does, others only have a custom-instructions or system-prompt field instead. Verified for this one:

Codex CLI auto-discovers skills from .agents/skills/spomory/SKILL.md, scanned from your current directory up to the repo root, plus ~/.agents/skills/ at the user level.

SKILL.md on GitHub →