Skip to content
selvedge

Codex MCP setup

Selvedge works with any compatible agent. This page covers one optional client integration; see general MCP and CLI setup for other agents.

Selvedge gives Codex a local store for project decisions and rejected approaches. Run selvedge setup --agent codex (0.3.12+) to install project MCP configuration and instructions together.

Before you start

Section titled “Before you start”

Install uv, then install the Selvedge CLI and MCP server:

Terminal window
uv tool install --upgrade selvedge

The MCP config below launches the server with uvx instead of a bare selvedge-server, so the package can be fetched on demand — the editor still needs to find uv installed. Prefer the global binary? Swap uvx --from selvedge selvedge-server for selvedge-server.

Add the MCP server

Section titled “Add the MCP server”

Add this to .codex/config.toml in a trusted project, or ~/.codex/config.toml for user-wide setup:

[mcp_servers.selvedge]
command = "uvx"
args = ["--from", "selvedge", "selvedge-server"]

Prefer not to touch config files? selvedge setup detects Codex and writes this for you (with a .bak first).

Tell your agent when to call it

Section titled “Tell your agent when to call it”

Selvedge captures decisions when your agent calls it. Install the instruction block into your project’s AGENTS.md:

Terminal window
selvedge prompt --install AGENTS.md

It’s also a copy-paste block on the site: the Selvedge agent prompt block.

Verify

Section titled “Verify”

Restart Codex in the trusted project. Enable the Selvedge MCP server in Settings → MCP servers if needed. Ask Codex to record a real rejected approach with log_change, then retrieve it with prior_attempts. Start a new session and query the same entity.

If it doesn’t connect

Section titled “If it doesn’t connect”

Codex project configuration loads only for trusted projects. The setup wizard writes .codex/config.toml and installs instructions in AGENTS.md. Custom TOML entries must be reconciled manually. Make sure uvx (manual setup) or selvedge-server (wizard setup) is on the PATH Codex uses. As of 0.3.15, setup also installs .codex/hooks.json. Review and trust those definitions with /hooks.

Next

Section titled “Next”