# Set up with Codex

Connect the Codex CLI to Unhandled with one command, and give Codex cloud or CI a token instead of a browser sign-in.

Codex reads Unhandled through the [MCP server](/docs/features/mcp-server) and runs under your own plan with its vendor.

## Connect

```bash
codex mcp add unhandled --url https://unhandled.net/mcp/x/debug
```

Or add it to `~/.codex/config.toml`:

```toml [~/.codex/config.toml]
[mcp_servers.unhandled]
url = "https://unhandled.net/mcp/x/debug"
```

The first tool call opens Unhandled's consent page in your browser. The URL is the `debug` [toolset](/docs/features/mcp-server#toolsets). More options are in the [Codex MCP docs](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

## Start it on an issue

```bash
npx @unhandled/cli login
npx @unhandled/cli fix https://unhandled.net/o/acme/projects/web/issues/42 --agent codex
```

Add `--headless` to run `codex exec` without a session. [Fix issues](/docs/agents/fix-issues) covers the rest.

## Without a browser

Codex cloud and CI cannot sign in through a browser. Create an [agent identity](/docs/features/mcp-server#agent-identities) under **Settings > MCP > Agent identities** and give Codex its token:

```bash
export UNHANDLED_TOKEN=unh_agent_...
codex mcp add unhandled --url https://unhandled.net/mcp/x/debug --bearer-token-env-var UNHANDLED_TOKEN
```

Grant read scopes only unless the job triages too. Sensitive calls still go to a person for approval.

## Next

- [Fix issues](/docs/agents/fix-issues): From the issue page, the CLI or a hand-off.
- [Security](/docs/agents/security): What a headless agent may do and who approves the rest.