OpenAI Codex

Connect Causely to OpenAI Codex to run reliability checks and incident triage alongside your coding workflows.

Prerequisites

Active Causely account
OpenAI Codex CLI installed. Update older builds first with npm i -g @openai/codex, since remote MCP and skills support landed in recent releases.
For skills: a Codex build with Agent Skills support

Setup

Setup is two steps: connect the MCP server, then add the skills. Step 1 registers the server and signs you in. The skills are a separate install covered in Step 2: Add the skills, and they are what route your questions to the right tools.

Step 1: Connect the server

codex mcp add causely --url https://api.causely.app/mcp
codex mcp login causely

The first command registers the server. The second opens a browser window for Causely OAuth login. After you authorize, Codex stores the token and refreshes it automatically, no API key to paste.

note

The Codex CLI, IDE extension, and ChatGPT desktop app share one MCP configuration on the same host. Adding the server once makes it available in all three.

Manual alternative

Add the following to ~/.codex/config.toml or project .codex/config.toml:

[mcp_servers.causely]
url = "https://api.causely.app/mcp"
enabled = true

Config file location

Scope	Path
User	`~/.codex/config.toml`
Project	`.codex/config.toml` at the repository root

Confirm the connection

Run codex mcp list to confirm causely appears, or type /mcp inside a Codex session to view connected servers. Codex reads MCP configuration at launch, so start a new session after any manual edit.

Step 2: Add the skills

Seven skills activate automatically once installed: one master router (causely-mcp) plus six specialists. See the Skills page for the full list, trigger phrases, and override options.

Codex reads skills as folders on disk and loads a skill on relevance, or you can invoke one on demand.

Install

Ensure that Skills are enabled for your Enterprise or Team plan.

Clone the Causely client repo

git clone https://github.com/causely-oss/causely-client
cd causely-client/skills

Copy the seven skill folders into a location Codex reads. Pick one of the two options below, they differ only in where the skills are available.

Option A, personal. Installs the skills once for your user account, available in every project. Copies into ~/.codex/skills/:

mkdir -p ~/.codex/skills
cp -r skills/causely-mcp skills/causely-alert-triage skills/causely-change-impact \
      skills/causely-correlated-incidents skills/causely-health-reporting \
      skills/causely-k8s-investigation skills/causely-postmortem \
      ~/.codex/skills/

Option B, project. Installs the skills into a single repository, available only when that repo is open, and shared with anyone who clones it. Commit .codex/skills/ to version control for team sharing. Replace <your-repo> with the path to the repository:

mkdir -p <your-repo>/.codex/skills
cp -r skills/causely-mcp skills/causely-alert-triage skills/causely-change-impact \
      skills/causely-correlated-incidents skills/causely-health-reporting \
      skills/causely-k8s-investigation skills/causely-postmortem \
      <your-repo>/.codex/skills/

tip

Codex also reads .claude/skills/ (project) and ~/.claude/skills/ (user). If you already installed the Causely skills for Claude Code, Codex picks them up with no extra steps.

Start a new Codex session. Skills load at startup. Type /skills to browse available skills and confirm the causely-* entries appear. Verify

In a Codex session, try: "What's broken right now?" The causely-health-reporting skill should activate.

Overrides

Invoke a specific specialist through the /skills selector, or name it in natural language: "use causely-postmortem: write a retrospective for the payment incident on April 25." To bypass skills entirely, call MCP tools directly. See the Full Tool Reference.

Try It Now

"List my clusters."
"Are there any active symptoms right now?"
"What services are currently degraded?"
"Draft a postmortem for the most recent incident."

Known Gotcha

Skills load at session start. Start a new Codex session after adding skills. A running session will not pick them up.
Sandbox execution. Codex runs sandboxed by default, so skills that call external scripts or tools may behave differently than in Claude Code, which runs directly in your terminal. The Causely reasoning skills (alert triage, postmortem, correlated incidents) are unaffected.
Directory name must match the skill name. The folders in the Causely repo already satisfy this. If you rename a folder, its name field in SKILL.md must match, or the skill fails to load with no error.
Remote OAuth is build-sensitive. Native OAuth for remote servers landed in recent Codex releases. If codex mcp login fails, update with npm i -g @openai/codex, or bridge the OAuth flow with mcp-remote: codex mcp add causely -- npx -y mcp-remote https://api.causely.app/mcp.
Machine credentials. For non-interactive or CI use instead of OAuth, use env_http_headers (reads from environment variables at runtime) rather than http_headers (static values in the file), to keep secrets out of the config:
```
[mcp_servers.causely]
url = "https://api.causely.app/mcp"
enabled = true

[mcp_servers.causely.env_http_headers]
"X-Causely-Client-Basic" = "CAUSELY_MCP_CLIENT_BASIC"
```
Export CAUSELY_MCP_CLIENT_BASIC to the Base64-encoded client_id:client_secret string before launching Codex. See Advanced Authentication for encoding instructions.

Prerequisites​

Setup​

Step 1: Connect the server​

Confirm the connection​

Step 2: Add the skills​

Try It Now​

Known Gotcha​