Skip to main content
Codex is an AI coding assistant that supports Model Context Protocol integrations. Connect the Orq MCP server to manage AI workflows directly from Codex, and route Codex’s model calls through the AI Gateway.

MCP Integration

Access the Orq.ai workspace directly from Codex. Manage experiments, query traces, and configure agents using natural language.

AI Gateway

Route Codex’s model calls through the AI Gateway for unified tracing and cost tracking.

​
MCP

With the Orq MCP integration, manage AI workflows directly from Codex while writing code.

​
Prerequisites

​
Installation

​
Add MCP Server via Terminal

Set the ORQ_API_KEY environment variable and add the Orq MCP server directly from the terminal:
Replace your-api-key-here with your actual API key from Workspace Settings → API Keys.

​
Add MCP Server via UI

  1. Open Codex Settings by clicking Codex → Settings in the top-left menu
  2. Click MCP Servers in the sidebar
  3. Click Connect to a custom MCP to open the configuration form
  4. Fill in the MCP server details:
    • Name: Orq.ai
    • Connection Type: Select Streamable HTTP tab
    • URL: https://my.orq.ai/v2/mcp
  5. Add authentication in the Environment variables section:
    • Click + Add environment variable
    • Key: AUTHORIZATION
    • Value: Bearer YOUR_ORQ_API_KEY
  6. Replace YOUR_ORQ_API_KEY with your actual API key from Workspace Settings → API Keys
  7. Click Save
The MCP server should connect automatically and all Orq.ai tools will be available immediately.

​
Verification

In Codex chat, ask:
If configured correctly, Codex will display AI models from the Orq.ai workspace.
Codex showing the Orq MCP server connected and tools available in the chat interface

Successfully connected Orq MCP in Codex

​
Available Commands

Use natural language to ask Codex to perform these operations:
  • Create an agent with custom instructions and tools
  • Get agent configuration for [agent-key]
  • Update agent [agent-key] with new instructions or model
  • Configure agent with evaluators and guardrails
  • Invoke agent [agent-key] with input [message]
  • Retrieve agent response [response-id]
  • Create a deployment called [deployment-key]
  • Get deployment configuration for [deployment-key]
  • Create a skill called [skill-key]
  • List all skills in my workspace
  • Get skill [skill-key]
  • Update skill [skill-key]
  • Delete skill [skill-key]
  • Get analytics overview for my workspace
  • Show me workspace metrics for the last 7 days
  • Query analytics filtered by deployment ID
  • Create a dataset called "customer-queries"
  • List all datapoints in dataset [dataset-key]
  • Add datapoints to dataset [dataset-key]
  • Update datapoint [datapoint-id]
  • Delete specific datapoints in dataset [dataset-key]
  • Delete dataset [dataset-key]
  • Create an experiment from dataset [dataset-key]
  • List all experiment runs
  • Export experiment run [run-id] as CSV
  • Run experiment and auto-evaluate results
  • Get evaluator configuration for [evaluator-key]
  • Create an LLM-as-a-Judge evaluator for tone
  • Create a Python evaluator to check response length
  • Add evaluator to experiment [experiment-key]
  • Update evaluator [evaluator-key] with a new prompt
  • Update Python evaluator [evaluator-key] with revised code
  • List traces from the last 24 hours
  • Show me traces with errors
  • Get span details for trace [trace-id]
  • Find the slowest traces from today
  • Show all traces for thread [thread-id]
  • List all available chat models
  • List all available embedding models
  • Invoke model [model-id] with prompt [message]
  • Search for datasets named "customer"
  • Find experiments in project [project-id]
  • List directories in project [project-id]
  • Search the Orq.ai docs for [topic]
  • Delete agent [agent-key]
  • Delete experiment [experiment-key]
  • Delete evaluator [evaluator-key]
  • Delete prompt [prompt-key]
  • Delete knowledge base [knowledge-base-key]
Use delete_dataset to delete a dataset along with all its datapoints.
See the MCP Quickstart for the full tool reference and examples.

​
Troubleshooting

  1. Verify the MCP endpoint URL
  2. Check the API key is valid
  3. Ensure network connectivity
  4. Review Codex logs for errors
  1. Confirm API key is valid
  2. Check API key permissions
  3. Try regenerating the API key
  4. Verify the Authorization header format
  1. Check the tool name is correct
  2. Verify required parameters are provided
  3. Review error messages in Codex
  4. Consult MCP tools list

​
Skills

Orq Skills add pre-built agentic workflows to Codex for the full Build, Evaluate, Optimize lifecycle.

​
Installation

Set an API key and connect the Orq MCP server first. Skills are then triggered by describing what is needed.

Orq Skills

The full catalogue of skills and slash commands.
Slash commands (/orq:quickstart, /orq:traces, and others) are only available in Claude Code.

​
AI Gateway

Route every model call Codex CLI makes through the Orq.ai AI Gateway by editing ~/.codex/config.toml. Requests appear in Traces automatically. Choose workspace credentials to use models from supported providers, or a ChatGPT subscription to run supported OpenAI models with the ChatGPT account signed in to Codex.

​
Prerequisites

​
Setup

Use this configuration to route model calls with the workspace’s provider credentials or Orq.ai credits. For subscription usage, follow ChatGPT subscription instead.
1

Export the API key

Replace <your-orq-api-key> with an API key. This sets the variable for the current shell session. To persist it across sessions, add the line to ~/.zshrc or ~/.bashrc.
2

Create or edit ~/.codex/config.toml

Create ~/.codex/config.toml if it does not exist. Add or merge the following keys. The top-level model and model_provider lines set the default; the [model_providers.orq] block registers the custom provider:
Replace openai/gpt-5.4 with the provider-prefixed model to use by default (e.g. anthropic/claude-sonnet-5). If a model key already exists in the file, replace it.
Do not name the provider openai. That identifier is reserved and hardcoded to api.openai.com. Setting base_url has no effect on it.
3

Run Codex

Running codex without flags routes all calls through the AI Gateway using the model configured in ~/.codex/config.toml.Pass --model to override the model for a single invocation:

​
ChatGPT subscription

Keep Codex signed in with ChatGPT and route its model calls through the AI Gateway for tracing. Model usage counts against the ChatGPT account’s Codex allowance instead of Orq.ai model credits. ChatGPT model access and usage limits still apply. Use a current Codex CLI release and a ChatGPT account with Codex access, in addition to the gateway prerequisites above.
1

Sign in with ChatGPT

Run codex login and choose ChatGPT sign-in. If already signed in, run codex login status to confirm the authentication method.
2

Export the gateway API key

In the shell that starts Codex, set:
The Orq.ai key authenticates access to the workspace. Codex manages the ChatGPT credential separately.
3

Configure the subscription provider

Merge the following into ~/.codex/config.toml, replacing any existing model, model_provider, and [model_providers.orq] settings:
Remove env_key and any [model_providers.orq.auth] block from the previous configuration. Codex sends its ChatGPT credential in Authorization and the Orq.ai key in x-orq-api-key.Select an openai/ model available to the ChatGPT account and enabled in the workspace. Other providers and custom model endpoints cannot use this subscription credential.
4

Run Codex and verify the trace

Start codex, send a prompt, and open Traces to find the request and its token usage.
The AI Gateway forwards model requests to the ChatGPT Codex backend and removes the Orq.ai key before forwarding. It does not fall back to workspace provider credentials when ChatGPT rejects a request. Codex’s native context compaction through the Responses API is supported. The separate /responses/compact endpoint, background Responses requests, and Orq.ai Agents do not support ChatGPT subscription credentials.

​
Configuration Reference

​
Tagging requests

Codex cannot modify the request body, so tag requests by adding this table below the existing provider configuration. Keep the authentication settings for the selected mode:
See Request Metadata for the full header reference and precedence rules.

​
Trace capture

Codex sends a stable session ID with each Responses request. The AI Gateway uses that ID to group the model round-trips from one Codex run into a session in Traces. Each round-trip remains a Responses trace and includes its model, token usage, cost, and tool calls.

​
Troubleshooting

Confirm ORQ_API_KEY is exported in the shell running Codex. Run test -n "$ORQ_API_KEY" && echo "ORQ_API_KEY is set" to check without printing the key.For ChatGPT subscription mode, run codex login status to confirm ChatGPT sign-in. Check that requires_openai_auth = true and env_http_headers contains "x-orq-api-key" = "ORQ_API_KEY", with no env_key or provider auth block.
Choose an openai/ model available to the signed-in ChatGPT account. A model listed in the AI Gateway catalog does not guarantee ChatGPT access. If the account reaches a usage limit, wait for the allowance to reset or switch to the workspace credential configuration above.
Update Codex to a release that uses native Responses compaction. Clients that call /responses/compact receive an error in subscription mode.
The model must be enabled in AI Gateway → Supported Models before Codex can route to it. Check that the model ID in config.toml uses the provider-prefixed format (e.g. openai/gpt-5.4, not gpt-5.6-sol).
Confirm base_url is https://my.orq.ai/v3/router and model_provider is set to the custom provider name (e.g. orq), not openai.
With approvals_reviewer = "auto_review" in ~/.codex/config.toml, Codex sends its internal model name codex-auto-review for automatic approval reviews. The AI Gateway resolves this name to openai/gpt-5.3-codex, so that model must be enabled in AI Gateway → Supported Models. To keep approval prompts interactive instead, set approvals_reviewer = "user" (the default).

​
Verification

Send a prompt in Codex. The response appears in the terminal, and the Codex session appears in Traces with its model identifier, turns, tool calls, token usage, and cost.