Skip to main content
Codex is an AI coding assistant that supports Model Context Protocol integrations. With Orq MCP, 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