Skip to main content
Claude Desktop integrates with Orq.ai through a plugin that bundles MCP and Skills, a standalone MCP connector, or Cowork inference through the AI Gateway.

Plugin (MCP + Skills)

Install workspace access and agentic workflows together.

MCP

Manage agents, experiments, and traces from Claude Desktop using natural language.

Skills

Pre-built agentic workflows for the Build, Evaluate, Optimize lifecycle.

Third-party inference (Cowork)

Route Cowork inference through the AI Gateway for fallbacks, EU residency, and cost control.

​
Plugin (MCP + Skills)

Install the Orq.ai plugin to add Skills, Commands, and the orq-workspace MCP connector together. The plugin uses an Orq.ai API key for workspace access, as defined in the plugin manifest.

​
Prerequisites

Organization administrators can distribute plugins through an organization marketplace.

​
Installation

1

Add the plugin marketplace

  1. Open Customize → Plugins in Claude Desktop.
  2. Open the Add menu and select Add marketplace → Add from a repository.
  3. Paste https://github.com/orq-ai/assistant-plugins into the repository URL field.
  4. Select the repository, then click Sync.
Claude Desktop Add marketplace dialog with the assistant-plugins GitHub repository entered

Add the Orq.ai plugin marketplace from GitHub

2

Install the plugin

Select Orq skills (orq-skills) from the assistant-plugins marketplace and click Add. Provide the Orq.ai API key when prompted.
Claude Desktop Orq skills plugin details showing Skills, Commands, Connectors, and Agents

Review the Orq.ai plugin and its bundled components

The plugin includes the MCP connector. Skip the standalone MCP installation for the same workspace; no separate OAuth connector is needed.

​
Verify Installation

Open the installed plugin details and confirm that Skills and Connectors → orq-workspace appear. Type / in a new chat to browse the bundled Skills and Commands. Enable the plugin connector from + → Connectors, and ask:
See Claude plugin documentation for plugin management and account syncing.

​
MCP

Claude Desktop is Anthropic’s desktop application that supports Model Context Protocol (MCP) integrations. By configuring the Orq MCP server, you can access all Orq.ai features directly in Claude Desktop conversations.

​
Prerequisites

For Team and Enterprise organizations, an organization owner or authorized administrator must add the connector first. Members connect to the provided connector instead of creating their own. See Claude custom connector setup.

​
Installation

1

Add a custom connector

  1. Open Claude Desktop Settings → Connectors.
  2. Click Add connector → Add custom connector.
  3. Enter Orq.ai as the name and https://my.orq.ai/v2/mcp as the server URL.
  4. Click Continue.
Claude Desktop custom connector form with the Orq.ai name and MCP server URL

Add the Orq.ai MCP server as a custom connector

2

Choose authentication

Use Sign in now with Register automatically selected. Leave request headers empty, then click Add.
Claude Desktop connector authentication with Sign in now and Register automatically selected

Sign in to Orq.ai using automatic OAuth registration

  1. Select No sign-in.
  2. Click Add header and choose authorization.
  3. Enter Bearer <ORQ_API_TOKEN>, replacing <ORQ_API_TOKEN> with an Orq.ai API key.
  4. Keep Required checked, then click Add.
No sign-in skips the OAuth browser flow. The request header still authenticates access with the API key.Team and Enterprise users of a connector share its API-key access. Use a key limited to the intended workspace access.
Claude Desktop No sign-in option with a required authorization header containing a placeholder bearer token

Authenticate the Orq.ai connector with an API-key header

3

Approve access in Orq.ai

For OAuth, complete the browser flow after clicking Add:
  1. Sign in to Orq.ai in the browser if prompted.
  2. On Approve MCP access, click Approve access.
  3. Return to Claude Desktop when the browser redirects back.
If the approval page shows Open ORQ sign in, follow that link, sign in, then return to the approval page and click Check again.Skip this step when using an API key.

​
Verify Installation

Start a new chat, enable the Orq.ai connector from + → Connectors, and ask:
Claude uses the Orq MCP integration to fetch and display available AI models.

​
What You Can Do

Once connected, you can use natural language in Claude Desktop 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.

​
Usage Examples

​
Create Experiments

Claude will:
  1. Use search_entities to find the “customer-queries” dataset
  2. Use create_experiment with the name “Model Comparison Test” and auto-run enabled
  3. Configure two task columns (one for GPT-5.6 Sol, one for Claude Sonnet 5)
  4. Execute both models against the dataset automatically via the auto-run option
  5. Provide a summary of the results with evaluation metrics

​
Analyze Traces

Claude will:
  1. Calculate the time range for the last 24 hours
  2. Use list_traces with error status filter
  3. Analyze the trace data
  4. Provide error count and types, affected deployments, time distribution, and suggested fixes based on error patterns

​
Generate Synthetic Datasets

Claude will:
  1. Generate 100 realistic customer support conversation examples (questions and expected responses)
  2. Use create_dataset to create a new dataset named “Support Training”
  3. Use create_datapoints to add all 100 conversations to the dataset
  4. Confirm creation with the dataset ID and sample of generated data

​
Performance Analysis

Claude will:
  1. Use query_analytics with a 7-day time range
  2. Analyze average latency changes over the week
  3. Review token usage patterns and cost trends
  4. Examine error rate fluctuations
  5. Compare performance across different models
  6. Provide a summary report with insights on whether performance has improved or decreased

​
Troubleshooting

  1. Open Settings → Connectors and confirm the Orq.ai connector uses https://my.orq.ai/v2/mcp.
  2. Complete the OAuth approval flow or check the API-key header.
  3. Start a new chat and enable the connector from + → Connectors.
For OAuth, confirm the browser is signed in to the intended Orq.ai account and workspace, then complete Approve access. If the approval page still requests sign-in, click Check again after signing in.For API-key authentication:
  1. Confirm the key is active and has access to the intended workspace in Orq.ai Settings.
  2. Select No sign-in and set the authorization header to Bearer <ORQ_API_TOKEN>.
  3. Keep Required checked.
MCP operations over HTTP can take a few seconds:
  • Be patient with large dataset operations
  • Break complex workflows into smaller steps
  • Check Orq.ai service status at uptime.orq.ai
  1. Confirm the Orq.ai connector is connected in Settings → Connectors.
  2. Start a new chat and enable the connector from + → Connectors.
  3. Try rephrasing the request.
  4. Check the MCP tools list.

​
Additional Configuration

​
Multiple Workspaces

OAuth uses the active workspace in the Orq.ai browser session when access is approved. Select the intended workspace before approving access. For separate API-key connections, add a custom connector for each workspace with a distinct name, such as Orq.ai Production and Orq.ai Staging. Use the same MCP server URL and an API key for the corresponding workspace. Enable the intended connector from + → Connectors in each chat.

​
Skills

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

​
Installation

Install the plugin to add Skills and the MCP connector together. Once installed, Claude selects a skill based on the task described.

Orq Skills

The full catalogue of skills and slash commands.
The plugin also includes Commands, listed in its detail view.

​
Third-party inference (Cowork)

Claude Cowork’s third-party inference mode routes all model inference through a configured gateway instead of Anthropic’s first-party infrastructure. Orq.ai’s AI Gateway speaks the Anthropic Messages API and is fully compatible.

EU data residency

Pin traffic to EU-hosted models to meet data residency requirements.

Provider fallback

Route across providers automatically to avoid rate limits and outages.

Cost control

Route to cheaper models for routine tasks by configuring them in Cowork.

​
Prerequisites

  • Claude Desktop installed with a Pro, Max, Team, or Enterprise plan
  • Active Orq.ai account with an API key

​
Setup

1

Enable Developer Mode

  1. Open Claude Desktop
  2. Click Help in the menu bar
  3. Hover over Troubleshooting
  4. Select Enable Developer Mode
  5. Restart Claude Desktop
A Developer menu appears in the menu bar after restart.
2

Open Gateway Configuration

  1. Click Developer in the menu bar
  2. Select Configure Third-party inference
  3. Select Gateway (Anthropic-compatible)
3

Enter Gateway Details

Fill in the three fields:
Cowork 3P inference gateway configuration screen showing Gateway selected as the connection type, with the Orq.ai base URL, API key, and bearer auth scheme filled in

Cowork gateway configuration with Orq.ai credentials

Click Apply locally to apply the configuration to this machine, or Export as MDM profile to deploy across an organization.
Get the API key from Orq.ai Settings under API Keys.
See the Anthropic Messages API for endpoint details, authentication, and cache_control breakpoints.
4

Add Models (optional)

Cowork automatically fetches available models from Orq.ai via the /v1/models endpoint, so no manual configuration is required. To pin a specific subset, add model slugs using the provider/model-name format:For the full catalog, see Supported Models.
5

Enable MCP tool search

Turn on Enable tool search (toolSearchEnabled) in the third-party inference configuration to load MCP tool definitions on demand. Click Apply locally, or export the updated MDM profile for managed devices. Fully quit and reopen Claude Desktop, then start a new session.See Enable MCP tool search for version requirements and managed-policy overrides.
6

Verify the Connection

A successful connection shows Cowork 3P | Gateway in the Cowork status indicator. All inference now routes through Orq.ai.

​
Use an Anthropic credential

To use an Anthropic API key or Claude subscription token for model usage, open Developer → Configure Third-party inference and select Gateway. Set the credentials as follows: Under Gateway extra headers, click Add and enter x-orq-api-key as the header name and the Orq.ai API key as its value. For a subscription token, run claude setup-token in a terminal and complete the browser sign-in. Paste the resulting token into Gateway API key without the Bearer prefix. Add another extra header named anthropic-beta with the value oauth-2025-04-20 for OAuth authentication. Select a public model served directly by Anthropic, such as anthropic/claude-sonnet-5, in Model list. Click Apply locally, then start a session and send a prompt. Check Traces for the request. Anthropic applies the supplied account’s API billing or subscription limits. Orq.ai records usage without charging the model request as Orq.ai-managed usage. See the Anthropic authentication guide for the header reference, or Anthropic’s Desktop gateway guide for the client configuration. For gateway connections, Claude Desktop disables MCP tool search by default. Enable toolSearchEnabled in the Desktop third-party inference configuration to avoid loading every MCP tool schema into the initial context. This setting requires Claude Desktop 1.21459.0 or later. Apply this setting through the configuration window, the managed Desktop profile, or the bootstrap response. It belongs to the Desktop inference configuration, not an MCP server’s env object in claude_desktop_config.json. Setting ENABLE_TOOL_SEARCH=true in a terminal alone does not override Desktop’s experimental-beta suppression. If devices also receive separate Claude Code managed settings, review policy precedence: those settings can override the Desktop toggle. Follow Anthropic’s toolSearchEnabled reference for the administrator override. After restarting, ask for an action that uses a connected MCP tool, then ask a follow-up that uses its result. Confirm both complete and inspect the requests in Traces. Tool discovery alone does not verify execution. For terminal sessions, follow the separate Claude Code setup.

​
Troubleshooting

Developer Mode is not enabled. Open Help → Troubleshooting → Enable Developer Mode, then restart Claude Desktop. The Developer menu appears only after a restart.
Enable MCP tool search in the Desktop inference configuration and restart the app. Check managed-policy overrides if tools still load upfront. Compare sessions with the same model and tools; system prompts, built-in tools, and conversation history also consume context.
Reopen Developer → Configure Third-party inference, confirm Gateway is selected, and verify the base URL is https://my.orq.ai/v3/anthropic. Use bearer for an Orq.ai key or Claude OAuth token, or x-api-key for an Anthropic API key.
Cowork fetches the catalog from the /v1/models endpoint. Confirm the base URL is https://my.orq.ai/v3/anthropic. When using an Anthropic credential, check that Gateway extra headers includes x-orq-api-key with a valid Orq.ai key. To pin a subset manually, add model slugs in the provider/model-name format.
Confirm the Cowork status indicator reads Cowork 3P | Gateway. If it still shows first-party inference, re-apply the configuration with Apply locally.

​
See Also

API Keys

Create and manage Orq.ai API keys.

Supported Models

Full catalog of models available through the AI Gateway.

AI Gateway

Get started with the AI Gateway for routing, fallbacks, and cost control.

Anthropic Provider

Configure the Anthropic API key and explore Claude model options.