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.

The agent is active straight away, with no approval step, but it starts deny-by-default with no scopes until you grant some in the dashboard .

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@latest", "mcp-server"]
env     = { AGENT_ID = "agt_...", OWNER_ID = "<your-owner-id>", PROXY_URL = "https://api.agentvalet.ai", AGENT_PRIVATE_KEY_PATH = "/path/to/.agentvalet/agent.key" }

You still need an agent and its private key, so run npx @agentvalet/register once and copy the values it prints. Without the env block the MCP server has no identity to sign with: the default registration doesn’t write the ~/.agentvalet/agent.json it would otherwise fall back to.

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 AgentValet provisions a new agent for the connection. Codex holds a short-lived access token from AgentValet’s OAuth server, not a signing key, and no raw credential sits in ~/.codex/config.toml. Get the URL pre-filled from app.agentvalet.ai → Agents → Connect Claude, ChatGPT, Copilot…, or find your owner ID under Settings → Account.

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.