naumudocs
ConnectorsCodex

Codex

Connect OpenAI's Codex CLI to your Naumu spaces over MCP, with browser sign-in or an API key.

Updated August 5, 20262 min read

Codex - OpenAI's coding agent - connects to Naumu over the same remote MCP server the Claude, ChatGPT, and local coding agent connectors use. Once connected, Codex acts on your behalf as the signed-in Naumu user, with your exact permissions, and you can revoke that access at any time.

This page is for developers running the Codex CLI. If you don't run a coding agent, you can skip it.

Remote MCP (browser sign-in)

Register Naumu's remote server with the Codex CLI:

bash
codex mcp add naumu --transport http https://naumu.ai/api/mcp

The first time Codex reaches the server, it opens your browser to sign in and approve access on the Naumu consent screen (powered by OAuth 2.1). There is no API key to create or paste. If you don't have a Naumu account yet, the sign-in page doubles as the signup page, so this first connection creates your account.

Use the front-end origin (naumu.ai), not a backend address. Sign-in and consent rely on your Naumu session, which lives on the front-end origin.

Remote-server support with browser OAuth is newer in the Codex CLI than in Claude or ChatGPT. If your Codex version doesn't yet handle the remote transport - the codex mcp add command errors, or sign-in never opens - use the API key path below, which works on every version.

API key (stdio) path

Every Codex version supports the older stdio transport, where Codex launches Naumu's local server itself. This path uses an API key instead of browser sign-in, and is also the right choice for CI jobs and other non-interactive runs.

  1. Open Settings → Your agents in Naumu, select Create an API key, and give it a recognizable name.
  2. Copy the key right away - it's shown only once and starts with nmu_.
  3. Register the local server with Codex, passing the key as an environment variable:
bash
codex mcp add naumu \
  --env NAUMU_API_KEY=nmu_your_key_here \
  -- npx -y -p @naumu/mcp naumu-mcp

The key lets the local server act in Naumu as you, with your exact permissions. See Local MCP for the full list of environment variables and stdio details, and Account settings for creating and revoking keys.

Use a separate API key for each tool. That way, if one leaks, you can revoke just that key without disrupting the others.

Revoke access

You can cut off Codex's access at any time in Naumu, under Settings → Your agents. The Active access list covers both browser sign-ins and API keys, and revoking either takes effect immediately.

Related

  • Local MCP - connect Claude Code and Cursor over the same remote MCP server.
  • Claude - connect claude.ai over a remote MCP connector.
  • Account settings - create and revoke the API keys CI jobs and bots use.
Anything missing?
Tell us what would make these docs better.
Local MCPRepo quickstart