# Codex Setup

Source checked: 2026-06-19
Official source: https://developers.openai.com/codex/mcp

Codex supports MCP servers and should be verified against current OpenAI Codex MCP docs before changing this path.

Core-specific rule: prefer the Core local bridge when a scoped connector key is available. Main history shows native Codex setup was fragile, and Core has a smoke test for the bridge path.

Recommended setup path:

1. Use native remote MCP: `codex mcp add core --url https://core.gradien.ai/mcp`.
2. Run `codex mcp login core` only when the protected-resource metadata advertises an authorization server.
3. If the user wants a guided CLI walkthrough, or native setup cannot be completed safely, run `npx -y @gradien/core-agent-setup install --base-url https://core.gradien.ai --yes --harness codex`.
4. Do not pass `--oauth-resource` for Core. Codex already discovers the OAuth resource from protected-resource metadata; adding it explicitly can make the provider reject the request because `resource` appears twice.
5. Do not pass `--scopes profile,email` for Core. Codex should prefer the server-advertised `scopes_supported`; narrowing scopes can mint a token that logs in but cannot select the Core workspace.
6. Tell the user that `http://127.0.0.1:<port>/callback/...` after browser login is normal: Codex receives the one-time OAuth code locally while the MCP server remains remote at the Core URL.
7. If Codex says OAuth needs an experimental flag, or an older Codex build fails while parsing OAuth metadata, check `codex --version` and tell the user to update Codex. Do not enable experimental OAuth flags as part of normal Core setup.
8. If `codex mcp login core` succeeds, do not inspect `.codex` auth/cache files and do not try to extract tokens for manual MCP calls. Codex owns those OAuth credentials.
9. Current Codex CLI versions do not expose a direct `codex mcp tools/list` probe. Verify with `codex mcp get core` and `codex mcp list`, then tell the user to restart Codex or open a fresh session so Core tools can load.
10. If a fresh Codex session still reports AuthRequired, stop broad diagnostics and run `codex mcp logout core`, then `codex mcp login core`, then restart or start another fresh Codex session.
11. If native OAuth still fails after a clean logout/login, fresh session, and current Codex version, fetch troubleshooting and consider the Core local bridge fallback.
12. The local bridge remains the proven fallback once a safe authenticated workspace credential is available.

If you cannot run commands, give the user a very short handoff and explain that it is a one-time local setup.

Troubleshooting: https://gradien.ai/core/docs/troubleshooting.md