Orq.ai MCP Server

What is Orq.ai MCP Server?

The Orq.ai MCP Server is Orq.ai's official remote MCP server. It connects Claude Code, Claude Desktop, Cursor, VS Code, Codex and Warp to your Orq.ai workspace so you can manage agents, datasets, experiments, evaluators and traces without leaving the editor.

Orq.ai is a platform for building and operating LLM applications: an AI gateway across model providers, managed agents, evaluation and experiments, observability, knowledge bases and governance. The MCP server, first released in beta in Orq.ai 4.4, now offers 38 tools across 11 categories. It is separate from Orq.ai's MCP Portal and MCP Gateway, which connect third-party MCP servers to Orq agents.

How to use Orq.ai MCP Server?

You need an Orq.ai account. The endpoint supports two authentication methods:

• OAuth: add the endpoint with no Authorization header. An OAuth-capable client opens the Orq.ai sign-in flow in your browser and requests access to the workspace.
• API key: set the header Authorization: Bearer YOUR_ORQ_API_KEY with a key from your Orq.ai workspace.

https://my.orq.ai/v2/mcp

Claude Code

From Orq.ai's docs (OAuth):

claude mcp add --transport http orq https://my.orq.ai/v2/mcp

To use an API key instead, add --header "Authorization: Bearer YOUR_ORQ_API_KEY".

Claude Desktop and claude.ai

Open Settings → Connectors → Add custom connector, name it "Orq.ai" and paste the URL, then complete the Orq.ai sign-in.

Cursor

Orq.ai's docs say to add the endpoint as a remote HTTP server and leave the headers empty for OAuth. In ~/.cursor/mcp.json:

{
  "mcpServers": {
    "orq": {
      "url": "https://my.orq.ai/v2/mcp"
    }
  }
}

VS Code

In .vscode/mcp.json:

{
  "servers": {
    "orq": {
      "type": "http",
      "url": "https://my.orq.ai/v2/mcp"
    }
  }
}

Complete the OAuth prompt in the browser when the client asks.

Key features of Orq.ai MCP Server

• Official Orq.ai server with OAuth sign-in or API-key auth.
• Agent management: create, update (with semantic versioning), invoke and retrieve agent responses.
• Datasets: create datasets and add, edit or delete datapoints (up to 100 at a time), including synthetic test data.
• Experiments: create runs from a dataset, list runs and export results as JSON, JSONL or CSV.
• Evaluators: create and update LLM-as-a-Judge and Python evaluators.
• Observability: list traces and spans with filters, and query workspace analytics for cost, latency, tokens and errors.
• Search across projects, prompts, agents and other entities, plus a docs search tool.
• Skills and deployments management from the same session.

Use cases of Orq.ai MCP Server

• Building an agent from chat: "Create a customer support agent called Support Bot that answers questions about our SaaS product, with a concise and professional tone."
• Regression testing: "Create a dataset from these 20 failing prompts and run an experiment comparing two models."
• Debugging production: "Which traces are throwing 500 errors since yesterday?"
• Knowledge base gaps: "List all queries that resulted in no knowledge base retrievals."
• Cost monitoring: "Is our average cost per request increasing, and which models drive spend?"
• Quality gates: "Add an LLM-as-a-Judge evaluator that checks answers for hallucinated prices."

Troubleshooting Orq.ai MCP Server

• A tool fails with "API key lacks permission". With an API key, each call runs under that key's permissions. Grant the needed permission or use OAuth, where calls run as the signed-in user.
• A read-only key still wrote data. Orq.ai notes its permission checks do not yet cover every write tool, so a read-only key is not a complete safeguard. Review which tools an agent may call.
• update_agent is rejected. Every update requires versionIncrement (major, minor or patch) and a versionDescription.
• You need something the MCP tools don't cover. Orq.ai's CLI covers a wider surface (prompts, budgets, webhooks and more) and suits scripts and CI.