Coreby Gradien

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

Codex supports remote MCP servers. Core can be registered as a remote MCP server and authenticated through Codex's OAuth flow.

Core MCP server URL:

https://core.gradien.ai/mcp

Run the guided installer:

npx -y @gradien/core-agent-setup install --base-url https://core.gradien.ai --yes --harness codex

The installer creates a short-lived Core signup/login session and registers Core with Codex.

Manual Setup

If you prefer to run the Codex commands yourself:

codex mcp add core --url https://core.gradien.ai/mcp
codex mcp login core

After browser login, a URL like http://127.0.0.1:<port>/callback/... is normal. That is the one-time local callback where Codex receives the OAuth code. The MCP server itself remains remote at https://core.gradien.ai/mcp.

Important Codex Notes

  • Do not add --oauth-resource for Core. Codex discovers the OAuth resource from Core protected-resource metadata, and adding it manually can duplicate the resource parameter.
  • Do not narrow OAuth to --scopes profile,email. Core may require the server-advertised scopes to select the correct workspace.
  • Do not extract or copy tokens from Codex auth/cache files. Codex owns those OAuth credentials.
  • Older Codex builds have had fragile OAuth behavior. If Codex reports an experimental OAuth flag requirement or fails while parsing metadata, update Codex and retry.

Verify

Check the saved MCP entry:

codex mcp get core
codex mcp list

Current Codex CLI versions may not expose a direct tools/list command. After setup and login, restart Codex or open a fresh Codex session so the Core tools can load.

If a fresh session still reports AuthRequired, run:

codex mcp logout core
codex mcp login core

Then restart Codex again. If native OAuth still fails on a current Codex version, use the Core local bridge fallback only after a safe scoped Core credential is available.