Codex | Spectron

Installing Spectron in the OpenAI Codex CLI gives Codex persistent memory across sessions, so it can recall previous decisions and project context without you repeating them.

For integration rules your agent should follow (auth, scope, endpoints, common mistakes), see Agent guide (AGENTS.md). You can add it to your project's AGENTS.md, which Codex reads automatically.

Configure

Codex reads MCP servers from ~/.codex/config.toml (or .codex/config.toml in a trusted project). Add a Streamable HTTP entry with a url and a bearer token sourced from an environment variable:

[mcp_servers.spectron]
url = "https://<your-context-host>/mcp"
bearer_token_env_var = "SPECTRON_API_KEY"
http_headers = { "X-Spectron-Context" = "acme-prod" }

Then export the key so Codex can read it:

export SPECTRON_API_KEY="<your-api-key>"

On SurrealDB Cloud, use your context host from Surrealist API keys (not a generic shared domain). Self-hosted: replace the URL with your Spectron server's base URL + /mcp.

Alternatively, add it from the terminal:

codex mcp add spectron --url https://<your-context-host>/mcp --bearer-token-env-var SPECTRON_API_KEY

Note

X-Spectron-Context is a client-side convenience for templating. Each API key is bound to one Context, so context_id is optional on every tool call; omit it to use the key's Context. An explicit value that does not match the key still returns 401.

Verify the installation

codex mcp list

You should see spectron listed. Start a Codex session and ask "What MCP tools do you have available?" Codex should report the Spectron tools. If it does not appear, check that the URL and the SPECTRON_API_KEY environment variable are correct.

Usage examples

Remember a decision as you work:

"Remember that we've standardised on Zod for request validation across the API services."

Codex calls memory_store with an appropriate scope (for example ["org/acme/project/api"]).

Recall context before a task:

"What did we decide about request validation?"

Codex calls memory_recall before answering.

Scope per tool call

Narrow reads and writes by passing a scope argument on each tool (slash paths, for example ["org/acme/project/api"]). Register paths with spectron scopes create before first use. For project isolation, use separate contexts or distinct scope paths.

Removing Spectron

Delete the [mcp_servers.spectron] block from ~/.codex/config.toml, or run codex mcp remove spectron.