Codex CLI quickstart

Codex reads its MCP config from ~/.codex/config.toml, one file, every project on the machine. Register AgentValet once and every Codex run on this machine is governed: scoped credentials, an audit log, no per-repo .env exports.

Requirements

Codex CLI installed
Node.js 18 or later
An AgentValet account. You don’t need to create one up front, the CLI signs you in via your browser the first time you run it.

Set up

Run this anywhere on your machine:


npx @agentvalet/register

Your browser opens to sign in (or sign up, it’s free). Once you authorise, the CLI generates an RS256 keypair, registers the agent, and writes the MCP entry to ~/.codex/config.toml, this is global by design, so the setup applies to every project you run Codex against. Pass --project and it also writes a project-scoped .codex/config.toml in the current directory (Codex treats project configs as trusted-projects-only).

The private key is written to .agentvalet/agent.key in the directory you ran the command from, with a .gitignore entry added automatically.

Approve the agent in the dashboard , it starts deny-by-default with no scopes until you grant some.

Prefer to wire it up by hand?

You can also use codex mcp add agentvalet … from the Codex CLI, or edit the TOML directly:


[mcp_servers.agentvalet]
command = "npx"
args    = ["-y", "@agentvalet/register", "mcp-server"]

You’ll still want to run npx @agentvalet/register once so the CLI has somewhere to store the agent’s private key.

Alternative: connect over OAuth

Codex supports Streamable HTTP MCP servers with OAuth. AgentValet implements Dynamic Client Registration, which is what Codex’s OAuth connect requires:


# Register AgentValet as a Streamable HTTP MCP server
codex mcp add agentvalet --url https://api.agentvalet.ai/mcp/v1/<your-owner-id>
 
# Open the browser OAuth flow
codex mcp login agentvalet

A browser tab opens for consent. Approve it and the agent gets its own signing identity, not a raw credential sitting in ~/.codex/config.toml. Find your owner ID at app.agentvalet.ai → Settings.

Confirm it loaded

Run codex normally. AgentValet should show up in the tool list any time the agent needs to call a platform.

Make your first governed call

Ask the agent to call list_platforms. It should return the platforms approved for this agent, an empty list at first, and that’s fine. What matters is that the call succeeds: your key signs correctly, the proxy is reachable, and the agent record is active.

From there, grant scopes for a platform you’ve connected in the dashboard and try a real call.