# Codex Setup

Official source: https://developers.openai.com/codex/mcp

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:

```text
https://core.gradien.ai/mcp
```

## Recommended Setup

Run the guided installer:

```bash
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:

```bash
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:

```bash
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:

```bash
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.