Connecting OpenAI Codex

OpenAI Codex CLI (@openai/codex) supports MCP servers via HTTP and stdio transport.

Prerequisites

Codex CLI installed: npm install -g @openai/codex
A HeadlessOps account with at least one workspace

Option A: Remote MCP (Recommended)

Add HeadlessOps to your Codex MCP configuration file (~/.codex/config.json or project-level codex.json):

{
  "mcpServers": {
    "headlessops": {
      "url": "https://app.headlessops.ai/mcp",
      "type": "http"
    }
  }
}

On first use, Codex will open your browser to authorize the connection via OAuth 2.1.

Option B: Local Proxy (Enables `folderPath`)

Install the local proxy to enable folderPath support for reading and writing local integration files.

Step 1 — Install the Proxy

npm install -g @headlessops-ai/mcp

Step 2 — Configure Codex

{
  "mcpServers": {
    "headlessops": {
      "command": "headlessops-mcp",
      "args": ["--mcp-url", "https://app.headlessops.ai/mcp"]
    }
  }
}

Or without a global install using npx:

{
  "mcpServers": {
    "headlessops": {
      "command": "npx",
      "args": ["-y", "@headlessops-ai/mcp", "--mcp-url", "https://app.headlessops.ai/mcp"]
    }
  }
}

macOS Homebrew Node: Use /opt/homebrew/bin/headlessops-mcp as the command if Codex doesn't inherit your shell PATH.

Workspace Resolution

Create iterator/iterator.config.json in your project root:

{ "workspaceId": "ws_abc123" }

To find your workspace ID: "List my HeadlessOps workspaces"

Example Prompts

Once connected:

"List all my HeadlessOps integrations"
"Create a webhook integration that logs incoming payloads"
"Show the last 5 failed runs of crm-sync"
"Fix the failing step in invoice-processor and redeploy"

Connect Codex (OpenAI)