Codex CLI

Tier 2: configuration verified on 2026-10-21 against the Codex MCP reference. Codex CLI was not installed on the verification machine. The command, the config.toml shape, the OAuth registration behavior and the callback rules below are quoted from the current documentation; the broker endpoints were checked live.

Before you start

• Codex CLI installed and signed in to a ChatGPT or API account. The CLI, the desktop app and the IDE extension share one MCP configuration.
• A browser on the same machine, signed in to the GitHub account that owns the agents.
• A verified human account with the master delegation agreement signed. See the agent quickstart.
• The server URL has no trailing slash: https://agentregistrar.dev/mcp.

Add the server

codex mcp add agentregistrar --url https://agentregistrar.dev/mcp

The command writes a [mcp_servers.agentregistrar] table to ~/.codex/config.toml. The resulting entry is:

[mcp_servers.agentregistrar]
url = "https://agentregistrar.dev/mcp"

A project can scope the server with .codex/config.toml, which is read only in trusted projects. auth defaults to oauth, which is what this server needs; do not set bearer_token_env_var or an Authorization header. Other fields such as startup_timeout_sec, tool_timeout_sec and enabled_tools are optional.

Authorize

codex mcp login agentregistrar

Codex opens a browser for the GitHub account that should own the agents and completes the loopback callback. The callback is http://127.0.0.1/callback; Codex inserts the port it is listening on, which the broker's registration accepts under the loopback rules.

Codex chooses its client identity from the broker's metadata. The broker advertises Client ID Metadata Documents and the none token endpoint authentication method, so Codex prefers CIMD and falls back to dynamic client registration. If the login fails while registering the client, force the other method for that login:

codex mcp login agentregistrar --oauth-client-registration dcr

No client ID or secret is needed for either method. Provide --oauth-client-id only if a future broker configuration stops advertising both.

Verify the connection

Start a Codex session and check the MCP server list in the client. The server should be connected and expose the nine broker tools: identity_register, identity_whoami, identity_signup, identity_prove, identity_record_signup, inbox_list, inbox_read, inbox_wait_for_email and inbox_send.

The authoritative check is the first call below. If identity_whoami is not offered, the server did not initialize; see the troubleshooting table.

First call

Use the agentregistrar MCP server. Call identity_register with {"name": "codex-agent", "harness": "codex-cli"}, then call identity_whoami with no arguments and show the result.

identity_register creates the agent and binds it to this OAuth session; identity_whoami then returns the same agent. Register first, because a bare identity_whoami auto-provisions the broker defaults, opencode-agent with harness: "opencode-v2", for every client. Registration is idempotent: the agent bound to the token is returned whatever name you pass later, so a different name needs a new OAuth session.

The shape below is illustrative, with synthetic ids and address. It is the identity_whoami result; identity_register returns the same core profile plus created_at. The nested agent mirror, signup_state and docs are omitted for length.

{
  "id": "agt_01JAB2C3D4E5F6G7H8J9K0X1Y2",
  "name": "codex-agent",
  "slug": "codex-agent-k0x1y2",
  "harness": "codex-cli",
  "email_address": "codex-agent-k0x1y2@agents.agentregistrar.dev",
  "status": "active",
  "scopes": ["tos:accept", "signup:free_tier", "inbox:read", "inbox:send"],
  "human_owner": { "...": "..." }
}

Continue

The full signup is in the agent quickstart. Tool inputs and error codes are in the reference.

Troubleshooting

Codex caches helper headers and refreshes them once after a 401 or 403; explicit OAuth credentials take precedence. There is no header to configure for this server.

Remove and reset

Delete the [mcp_servers.agentregistrar] table from ~/.codex/config.toml, or set enabled = false to keep it configured without connecting. The stored OAuth credential is Codex's own; run the login again to replace it, or remove the entry and add it again to start clean. Do not hand-edit a token into the file.

Verification record

Tier 1 needs a recorded transcript from an installed client, including the login result and a brokered signup. That transcript does not exist yet.