codex_cli_mcp.md

Codex CLI MCP Setup

Install Atlas Once:

uv tool install git+https://github.com/nshkrdotcom/atlas_once
atlas install --profile nshkrdotcom

For local checkout development, deliberately reinstall from the checkout:

uv tool install --reinstall /path/to/atlas_once

uv run atlas ... is useful in the checkout, but it does not install atlas-mcp for Codex. Codex starts MCP servers from its own process environment, so atlas-mcp must be on normal PATH.

Generate the Atlas-owned MCP client snippet:

atlas config mcp install
atlas config mcp show
atlas config mcp doctor

The generated snippet uses the stable atlas-mcp command, not a source checkout path. Add that snippet to Codex or another MCP-capable client using the client’s MCP configuration flow. The same installer command also writes the repo-owned atlas-codex skill under Atlas-managed MCP config so the skill travels with package installs.

Register Atlas in Codex:

codex mcp add atlas-once --env ATLAS_ONCE_PROFILE=nshkrdotcom -- atlas-mcp
codex mcp list
codex mcp get atlas-once

Test the server:

atlas-mcp --help
atlas mcp doctor
atlas mcp tools --json

Recommended Codex instructions:

• Prefer Atlas MCP tools over shell commands for Atlas workflows.
• Use read tools before write tools.
• Use write tools only when explicitly asked and pass confirm_write=true.
• Do not edit Atlas config directly; use installer/config commands.
• Use nshkrdotcom as the installed default profile for this user.
• Use gn-twelve as the primary ranked group; gn-ten and gn-eleven remain available.
• Keep core Atlas behavior generic and keep the default profile host-neutral.