Skip to main content

​
Overview

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 your Claude Desktop conversations.

​
Prerequisites

​
Installation

You can configure the Orq MCP server through Claude Desktop Settings or using the Terminal.
  1. Open Claude Desktop Settings by clicking Claude in the top-left menu, then select Settings
  2. Click Developer in the sidebar
  3. Click Edit Config to open the claude_desktop_config.json file
  4. 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>"
      }
    }
  }
}
  1. Replace <ORQ_API_TOKEN> with your actual API key from Workspace Settings → API Keys
  2. 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 the orq server to the existing mcpServers object.

​
Option 2: Terminal Path

If you prefer using the terminal, you can directly edit the config file: macOS: Run these commands in your terminal: 
# Open the config file in your default text editor
open ~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows: Run this command in your Command Prompt or PowerShell: 
# Open the config file in Notepad
notepad %APPDATA%\Claude\claude_desktop_config.json
Linux: Run this command in your terminal: 
# Open the config file in nano (or use your 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 MCP integration to fetch and display your available AI models.
Claude Desktop MCP Success

​
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-id]
  • Configure agent with evaluators and guardrails
  • 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-id]
  • Add datapoints to dataset [dataset-id]
  • Update datapoint [datapoint-id]
  • Delete dataset [dataset-id]
  • Create an experiment from dataset [dataset-id]
  • List all experiment runs
  • Export experiment run [run-id] as CSV
  • Run experiment and auto-evaluate results
  • Create an LLM-as-a-Judge evaluator for tone
  • Create a Python evaluator to check response length
  • Add evaluator to experiment [experiment-id]
  • 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

​
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:
  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.2, one for Claude Sonnet 4.6)
  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

Show me all errors from my Orq traces in the last 24 hours
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

Generate 100 realistic customer support conversations about a SaaS product
and create a dataset called "Support Training" in Orq
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

Has my system's performance improved over the last week?
Show latency trends and cost metrics from Orq analytics.
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. Verify the config file path is correct for your OS
  2. Check the JSON syntax is valid (no trailing commas, proper quotes)
  3. Ensure your API key is valid and has the required permissions
  4. Restart Claude Desktop after making config changes
  5. Check the Claude Desktop logs for error messages
  1. Confirm your API key is active in Orq.ai Settings
  2. Make sure the API key has workspace access permissions
  3. Verify the Authorization header format: Bearer YOUR_KEY
  4. Try generating a new API key if the current one is expired
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
  1. Verify the MCP server is properly configured in your config file
  2. Restart Claude Desktop to reload the MCP configuration
  3. Try rephrasing your request
  4. Check the MCP tools list

​
Additional Configuration

​
Multiple Workspaces

If you work with multiple Orq.ai workspaces, you can configure multiple MCP servers: 
{
  "preferences": {
    "sidebarMode": "chat",
    "coworkScheduledTasksEnabled": false
  },
  "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>"
      }
    }
  }
}