> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Desktop | MCP

> Connect your Orq.ai workspace to Claude Desktop. Access your workspace, run experiments, and analyze traces directly from the desktop app.

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

### Prerequisites

* [Claude Desktop app](https://claude.ai/download) installed
* Active Orq.ai account
* [Orq.ai API key](/docs/administer/api-keys)
* [Node.js](https://nodejs.org/) installed (required for `npx mcp-remote`)

### Installation

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

<AccordionGroup>
  <Accordion title="Option 1: Settings Path (Recommended)" icon="sliders">
    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:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "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>"
          }
        }
      }
    }
    ```

    5. Replace `<ORQ_API_TOKEN>` with your actual API key from [Workspace Settings → API Keys](https://my.orq.ai/settings/api-keys)
    6. Save the file and restart Claude Desktop

    <Note>
      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.
    </Note>
  </Accordion>

  <Accordion title="Option 2: Terminal Path" icon="terminal">
    If you prefer using the terminal, you can directly edit the config file:

    **macOS:**

    Run these commands **in your terminal**:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    # 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**:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    # Open the config file in Notepad
    notepad %APPDATA%\Claude\claude_desktop_config.json
    ```

    **Linux:**

    Run this command **in your terminal**:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    # Open the config file in nano (or use your preferred editor)
    nano ~/.config/Claude/claude_desktop_config.json
    ```

    Then paste the following configuration:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "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.

    <Note>
      If the file doesn't exist, the command will create it. Make sure to use valid JSON formatting.
    </Note>
  </Accordion>
</AccordionGroup>

### Verify Installation

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

```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
Can you list the available models from Orq?
```

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

<Frame caption="Successfully connected Orq MCP in Claude Desktop">
  <img src="https://mintcdn.com/orqai/rjY3PTYrNubA6L2q/images/mcp-claude-desktop-success.png?fit=max&auto=format&n=rjY3PTYrNubA6L2q&q=85&s=f8cdeefc02d0b3c4866309582a59537f" alt="Claude Desktop MCP Success" width="2272" height="1760" data-path="images/mcp-claude-desktop-success.png" />
</Frame>

### What You Can Do

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

<AccordionGroup>
  <Accordion title="Agents" icon="robot">
    * `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`
  </Accordion>

  <Accordion title="Analytics" icon="chart-line">
    * `Get analytics overview for my workspace`
    * `Show me workspace metrics for the last 7 days`
    * `Query analytics filtered by deployment ID`
  </Accordion>

  <Accordion title="Datasets" icon="database">
    * `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]`
  </Accordion>

  <Accordion title="Experiments" icon="flask">
    * `Create an experiment from dataset [dataset-key]`
    * `List all experiment runs`
    * `Export experiment run [run-id] as CSV`
    * `Run experiment and auto-evaluate results`
  </Accordion>

  <Accordion title="Evaluators" icon="clipboard-check">
    * `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`
  </Accordion>

  <Accordion title="Traces" icon="chart-bullet">
    * `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]`
  </Accordion>

  <Accordion title="Models" icon="microchip">
    * `List all available chat models`
    * `List all available embedding models`
  </Accordion>

  <Accordion title="Registry" icon="filter">
    * `List registry keys for filtering traces`
    * `List top values for [attribute-key]`
  </Accordion>

  <Accordion title="Search" icon="magnifying-glass">
    * `Search for datasets named "customer"`
    * `Find experiments in project [project-id]`
    * `List directories in project [project-id]`
  </Accordion>

  <Accordion title="Documentation" icon="book-open">
    * `Search the Orq.ai docs for [topic]`
  </Accordion>

  <Accordion title="Managing Entities" icon="trash">
    * `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.
  </Accordion>
</AccordionGroup>

### Usage Examples

#### Create Experiments

```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

<AccordionGroup>
  <Accordion title="MCP Server Not Connecting">
    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
  </Accordion>

  <Accordion title="Authentication Errors">
    1. Confirm your API key is active in [Orq.ai Settings](https://my.orq.ai/settings/api-keys)
    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
  </Accordion>

  <Accordion title="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](https://status.orq.ai)
  </Accordion>

  <Accordion title="Tool Not Found">
    1. Verify the **Orq MCP** server is properly configured in your config file
    2. Restart Claude Desktop to reload the **Orq MCP** configuration
    3. Try rephrasing your request
    4. Check the [MCP tools list](/docs/integrations/code-assistants/mcp#available-tools)
  </Accordion>
</AccordionGroup>

### Additional Configuration

#### Multiple Workspaces

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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](/docs/integrations/code-assistants/skills) page for the full reference.

### Installation

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

<Note>
  Custom Skills require a Pro, Max, Team, or Enterprise plan. To install, open [Claude.ai](https://claude.ai) in your browser, go to **Settings → Features → Skills**, and upload the [orq-skills zip](https://github.com/orq-ai/assistant-plugins/archive/refs/heads/main.zip).
</Note>

### 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 Router for zero-code traces, or OpenTelemetry for framework-level spans |
| **compare-agents**             | Run cross-framework agent comparisons using evaluatorq                                                                      |

<Note>
  Slash commands (`/orq:quickstart`, `/orq:traces`, etc.) are only available in Claude Code. See [Skills](/docs/integrations/code-assistants/skills) for details.
</Note>