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 and runs under your own plan with its vendor.

Connect

Terminal

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

Or add it to ~/.codex/config.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. More options are in the Codex MCP docs.

Terminal

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 covers the rest.

Codex cloud and CI cannot sign in through a browser. Create an agent identity under Settings > MCP > Agent identities and give Codex its token:

Terminal

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.

From the issue page, the CLI or a hand-off.

What a headless agent may do and who approves the rest.