Coreby Gradien
Docs
Start free today

Agent guide

Codex Setup

Back to setup docsRaw source

Paste this into your agent

Start with this visible request when you want the agent to help. It keeps the action coming from you, while the linked setup reference stays plain and non-recursive.

Use this in the app you are connecting, then approve only the browser login, app setting, or restart steps that the app requires.

Please help me set up Core for Codex. Core is a home base for AI agents: it keeps memory, files, decisions, tasks, and work context synced across tools, harnesses, and models.

Use this official setup reference:
https://gradien.ai/core/docs/reference.txt

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