Claude Desktop | MCP, Skills & Cowork

Claude Desktop integrates with Orq.ai in three ways: connect the MCP server for workspace access, install Skills for agentic workflows, or route Cowork inference through the AI Gateway.

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.

MCP

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

Prerequisites

Claude Desktop app installed
Active Orq.ai account
Orq.ai API key
Node.js installed (required for npx mcp-remote)

Installation

You can configure the Orq MCP server through Claude Desktop Settings or using the Terminal.

Option 1: Settings Path (Recommended)

Open Claude Desktop Settings by clicking Claude in the top-left menu, then select Settings
Click Developer in the sidebar
Click Edit Config to open the claude_desktop_config.json file
Paste the following configuration into the file:

{
  "preferences": {
    "sidebarMode": "chat",
    "coworkScheduledTasksEnabled": false
  },
  "mcpServers": {
    "orq": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://my.orq.ai/v2/mcp",
        "--header",
        "Authorization:${ORQ_AUTH_HEADER}"
      ],
      "env": {
        "ORQ_AUTH_HEADER": "Bearer <ORQ_API_TOKEN>"
      }
    }
  }
}

Replace <ORQ_API_TOKEN> with your actual API key from Workspace Settings → API Keys
Save the file and restart Claude Desktop

If the config file is empty, paste the entire JSON structure above. If it already has content, add only the orq entry to the existing mcpServers object. Do not overwrite the preferences block or any other existing keys.

Option 2: Terminal Path

If you prefer using the terminal, you can directly edit the config file:macOS:Run these commands in the terminal:

# Open the config file in the default text editor
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows:Run this command in Command Prompt or PowerShell:

# Open the config file in Notepad
notepad %APPDATA%\Claude\claude_desktop_config.json

Linux:Run this command in the terminal:

# Open the config file in nano (or any preferred editor)
nano ~/.config/Claude/claude_desktop_config.json

Then paste the following configuration:

{
  "preferences": {
    "sidebarMode": "chat",
    "coworkScheduledTasksEnabled": false
  },
  "mcpServers": {
    "orq": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://my.orq.ai/v2/mcp",
        "--header",
        "Authorization:${ORQ_AUTH_HEADER}"
      ],
      "env": {
        "ORQ_AUTH_HEADER": "Bearer <ORQ_API_TOKEN>"
      }
    }
  }
}

Replace <ORQ_API_TOKEN> with your actual API key, save the file, and restart Claude Desktop.

If the file doesn’t exist, the command will create it. Make sure to use valid JSON formatting.

Verify Installation

After restarting Claude Desktop, start a new conversation and ask:

Can you list the available models from Orq?

Claude will use the Orq MCP integration to fetch and display available AI models.

Claude Desktop MCP Success — Successfully connected Orq MCP in Claude Desktop

What You Can Do

Once connected, you can use natural language in Claude Desktop to perform these operations:

Agents

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]

Deployments

Create a deployment called [deployment-key]
Get deployment configuration for [deployment-key]

Skills

Create a skill called [skill-key]
List all skills in my workspace
Get skill [skill-key]
Update skill [skill-key]
Delete skill [skill-key]

Analytics

Get analytics overview for my workspace
Show me workspace metrics for the last 7 days
Query analytics filtered by deployment ID

Datasets

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]

Experiments

Create an experiment from dataset [dataset-key]
List all experiment runs
Export experiment run [run-id] as CSV
Run experiment and auto-evaluate results

Evaluators

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

Traces

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]

Models

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]

Documentation

Search the Orq.ai docs for [topic]

Managing Entities

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

Create an experiment called "Model Comparison Test" using my "customer-queries" dataset.
Configure it with GPT-5.2 and Claude Sonnet 4.6, then run it.

Claude will:

Use search_entities to find the “customer-queries” dataset
Use create_experiment with the name “Model Comparison Test” and auto-run enabled
Configure two task columns (one for GPT-5.2, one for Claude Sonnet 4.6)
Execute both models against the dataset automatically via the auto-run option
Provide a summary of the results with evaluation metrics

Analyze Traces

Show me all errors from my Orq traces in the last 24 hours

Claude will:

Calculate the time range for the last 24 hours
Use list_traces with error status filter
Analyze the trace data
Provide error count and types, affected deployments, time distribution, and suggested fixes based on error patterns

Generate Synthetic Datasets

Generate 100 realistic customer support conversations about a SaaS product
and create a dataset called "Support Training" in Orq

Claude will:

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

Performance Analysis

Has my system's performance improved over the last week?
Show latency trends and cost metrics from Orq analytics.

Claude will:

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

Troubleshooting

MCP Server Not Connecting

Verify the config file path is correct for the OS in use
Check the JSON syntax is valid (no trailing commas, proper quotes)
Ensure the API key is valid and has the required permissions
Restart Claude Desktop after making config changes
Check the Claude Desktop logs for error messages

Authentication Errors

Confirm the API key is active in Orq.ai Settings
Make sure the API key has workspace access permissions
Verify the Authorization header format: Bearer YOUR_KEY
Try generating a new API key if the current one is expired

Slow Responses

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 status.orq.ai

Tool Not Found

Verify the Orq MCP server is properly configured in the config file
Restart Claude Desktop to reload the Orq MCP configuration
Try rephrasing the request
Check the MCP tools list

Additional Configuration

Multiple Workspaces

If you work with multiple Orq.ai workspaces, you can configure multiple MCP servers:

{
  "mcpServers": {
    "orq-production": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://my.orq.ai/v2/mcp",
        "--header",
        "Authorization:${ORQ_PROD_AUTH_HEADER}"
      ],
      "env": {
        "ORQ_PROD_AUTH_HEADER": "Bearer <PRODUCTION_API_TOKEN>"
      }
    },
    "orq-staging": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://my.orq.ai/v2/mcp",
        "--header",
        "Authorization:${ORQ_STAGING_AUTH_HEADER}"
      ],
      "env": {
        "ORQ_STAGING_AUTH_HEADER": "Bearer <STAGING_API_TOKEN>"
      }
    }
  }
}

Skills

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

Installation

Skills for Claude Desktop are managed through the Claude.ai web interface and automatically apply across all Claude clients, including the desktop app.

Custom Skills require a Pro, Max, Team, or Enterprise plan. To install, open Claude.ai, go to Settings → Features → Skills, and upload the orq-skills zip.

Available Skills

Once installed, Claude picks the right skill automatically based on what you describe.

Skill	Description
build-agent	Design, create, and configure an Orq.ai agent
build-evaluator	Create validated LLM-as-a-Judge evaluators
analyze-trace-failures	Read production traces and categorize failures
run-experiment	Create and run experiments with evaluation
generate-synthetic-dataset	Generate and curate evaluation datasets
optimize-prompt	Analyze and optimize system prompts
setup-observability	Instrument LLM applications with orq.ai tracing: AI Gateway for zero-code traces, or OpenTelemetry for framework-level spans
compare-agents	Run cross-framework agent comparisons using evaluatorq

Slash commands (/orq:quickstart, /orq:traces, etc.) are only available in Claude Code. See Skills for details.

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

Enable Developer Mode

Open Claude Desktop
Click Help in the menu bar
Hover over Troubleshooting
Select Enable Developer Mode
Restart Claude Desktop

A Developer menu appears in the menu bar after restart.

Open Gateway Configuration

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

Enter Gateway Details

Fill in the three fields:

Field	Value
Gateway base URL	`https://api.orq.ai/v3/anthropic`
Gateway API key	The Orq.ai API key
Gateway auth scheme	`bearer`

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.

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:

Model slug	Description
`anthropic/claude-sonnet-4-6`	Claude Sonnet via Anthropic direct
`aws/anthropic/claude-sonnet-4-6`	Claude Sonnet via AWS Bedrock
`google/anthropic/claude-opus-4-7`	Claude Opus via Google Vertex AI
`openai/gpt-4o`	GPT-4o for routine tasks

For the full catalog, see Supported Models.

Verify the Connection

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

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.

AI Providers

Coding Assistants

Frameworks

Automations

Claude Desktop | MCP, Skills & Cowork

MCP

Skills

Third-party inference (Cowork)

MCP

Prerequisites

Installation

Verify Installation

What You Can Do

Usage Examples

Create Experiments

Analyze Traces

Generate Synthetic Datasets

Performance Analysis

Troubleshooting

Additional Configuration

Multiple Workspaces

Skills

Installation

Available Skills

Third-party inference (Cowork)

EU data residency

Provider fallback

Cost control

Prerequisites

Setup

See Also

API Keys

Supported Models

AI Gateway

Anthropic Provider

MCP

Skills

Third-party inference (Cowork)

​MCP

​Prerequisites

​Installation

​Verify Installation

​What You Can Do

​Usage Examples

​Create Experiments

​Analyze Traces

​Generate Synthetic Datasets

​Performance Analysis

​Troubleshooting

​Additional Configuration

​Multiple Workspaces

​Skills

​Installation

​Available Skills

​Third-party inference (Cowork)

EU data residency

Provider fallback

Cost control

​Prerequisites

​Setup

​See Also

API Keys

Supported Models

AI Gateway

Anthropic Provider

MCP

Prerequisites

Installation

Verify Installation

What You Can Do

Usage Examples

Create Experiments

Analyze Traces

Generate Synthetic Datasets

Performance Analysis

Troubleshooting

Additional Configuration

Multiple Workspaces

Skills

Installation

Available Skills

Third-party inference (Cowork)

Prerequisites

Setup

See Also