> ## 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 Code | MCP & AI Router
> Integrate Orq.ai with Claude Code CLI using MCP. Access your workspace, manage experiments, and analyze traces from your terminal.
Access your Orq.ai workspace directly from Claude Code. Manage experiments, query traces, and configure agents using natural language.
AI Router Beta} icon="arrow-right-arrow-left" href="#ai-router">
Route Claude Code's model calls through the **AI Router**.
## MCP
Claude Code is Anthropic's official CLI that brings Claude's capabilities to your terminal and development workflow. With the Orq MCP integration, you can access all Orq.ai features directly through Claude Code's conversational interface.
### Prerequisites
* [Claude Code CLI](https://github.com/anthropics/claude-code) installed
* Active Orq.ai account
* [Orq.ai API key](/docs/administer/api-keys)
### Installation
Add the Orq MCP server to Claude Code with a single command:
```bash wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
claude mcp add --transport http orq https://my.orq.ai/v2/mcp --header "Authorization: Bearer ${ORQ_API_KEY}"
```
Make sure to set your `ORQ_API_KEY` environment variable before running the command:
```bash wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
export ORQ_API_KEY="your-api-key-here"
```
### Verify Installation
Check that the Orq MCP is installed:
```bash wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
claude mcp list
```
You should see `orq` in the list of available MCP servers.
### Available Commands
Once integrated, you can ask Claude Code 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`
* `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`
* `List registry keys for filtering traces`
* `List top values for [attribute-key]`
* `Search for datasets named "customer"`
* `Find experiments in project [project-id]`
* `Find experiments in project [project-key]`
* `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 an Experiment
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
Create an experiment called "GPT-5.2 vs Claude Sonnet 4.6 Comparison" using the "customer-queries" dataset
```
Claude Code will:
1. Use `search_entities` to find the "customer-queries" dataset
2. Use `create_experiment` with the specified name and dataset ID
3. Configure task columns with GPT-5.2 and Claude Sonnet 4.6 models
4. Return the experiment ID and configuration details
#### Query Trace Analytics
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
Has my system thrown any errors in the last 24 hours?
```
Claude Code will:
1. Calculate the time range for the last 24 hours
2. Use `list_traces` with error status filter
3. Analyze the error data
4. Provide a summary of total error count, error types and frequencies, affected traces, and time distribution
#### Create a Synthetic Dataset
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
Create a dataset called "Product Questions" with 50 synthetic customer questions about e-commerce products
```
Claude Code will:
1. Generate 50 synthetic customer questions about e-commerce products
2. Use `create_dataset` to create a new dataset named "Product Questions"
3. Use `create_datapoints` to add all 50 questions to the dataset
4. Confirm creation with the dataset ID and summary
#### Performance Analysis
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
Has my system's performance improved or decreased over the past week?
```
Claude Code will:
1. Use `query_analytics` with a 7-day time range
2. Analyze average latency trends over time
3. Review token usage patterns and cost variations
4. Compare error rate changes across the week
5. Provide insights on model performance comparisons and trends
#### Complete Experiment Creation
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
I have a CSV file with 100 customer queries. Create a dataset, add an LLM evaluator for tone and accuracy, then run an experiment comparing GPT-5.2 and Claude Sonnet 4.6
```
Claude Code will:
1. Read and parse your CSV file
2. Use `create_dataset` to create a new dataset with an auto-generated name
3. Use `create_datapoints` to add all 100 customer queries from the CSV
4. Use `create_llm_eval` to create an LLM-as-a-Judge evaluator for tone
5. Use `create_llm_eval` again to create an LLM-as-a-Judge evaluator for accuracy
6. Use `create_experiment` with the dataset ID and auto-run enabled
7. Configure two task columns (one for GPT-5.2, one for Claude Sonnet 4.6)
8. Execute the experiment automatically via the auto-run option
9. Summarize the results with evaluation scores for both models
#### Trace Investigation
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
Show me the 10 slowest traces from yesterday and explain what might be causing the latency
```
Claude Code will:
1. Calculate yesterday's date range
2. Use `list_traces` with latency sorting (descending) and limit of 10
3. Use `list_spans` to retrieve span information for each trace
4. Analyze the execution patterns and span durations
5. Provide performance insights identifying bottlenecks
6. Suggest optimization opportunities based on the data
### Troubleshooting
1. Verify your API key is valid: `echo $ORQ_API_KEY`
2. Check the API key has the necessary permissions
3. Re-add the MCP with the correct API key
1. Verify the endpoint URL is correct
2. Check your internet connection
3. Try removing and re-adding the integration
1. Get MCP server details: `claude mcp get orq`
2. Verify the MCP is properly installed: `claude mcp list`
## Plugins
The [`orq-ai/claude-plugins`](https://github.com/orq-ai/claude-plugins) marketplace exposes three plugins for Claude Code. Add the marketplace once, then install whichever plugins you need:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
claude plugin marketplace add orq-ai/claude-plugins
```
| Plugin | Purpose |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `orq-skills` | Pre-built agentic workflows and slash commands for the Build, Evaluate, Optimize lifecycle. Includes the Orq MCP server. |
| `orq-mcp` | Standalone Orq MCP server. Use this if you only want platform tool access without the skills bundle. |
| `orq-trace` | Automatically traces Claude Code sessions to orq.ai: captures sessions, turns, tool calls, and LLM responses as hierarchical OTLP spans. |
`orq-skills` already bundles the MCP server. Don't install `orq-mcp` alongside it or the MCP will be registered twice.
### Skills
**Skills** extend Claude Code with pre-built agentic workflows for the full Build, Evaluate, Optimize lifecycle. See the [Skills](/docs/integrations/code-assistants/skills) page for the full reference.
#### Installation
```bash Plugin (recommended) theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Requires marketplace to be added first (see Plugins section above)
# Installs skills, commands, agents, and the MCP server
claude plugin install orq-skills@orq-claude-plugin
```
```bash Local clone theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Clone and load locally as a fallback
git clone https://github.com/orq-ai/assistant-plugins.git ~/.orq-skills
claude --plugin-dir ~/.orq-skills
```
### MCP server only
If you only want the Orq MCP server without the skills bundle, install `orq-mcp` instead:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
claude plugin install orq-mcp@orq-claude-plugin
```
This gives Claude access to orq.ai platform tools (agents, analytics, traces, experiments) without registering the agentic workflows.
### Session tracing
The `orq-trace` plugin captures every Claude Code session as a hierarchical trace in orq.ai: useful for reviewing past coding sessions, sharing context with teammates, or analyzing tool-call patterns across runs.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
claude plugin install orq-trace@orq-claude-plugin
```
Set `ORQ_API_KEY` in your environment so the plugin can ship spans to your workspace. Sessions appear under [Traces](/docs/observability/traces) once the next session starts.
### Commands
Quick slash-command actions available in Claude Code:
| Command | Description |
| ----------------- | ----------------------------------------------------------- |
| `/orq:quickstart` | Interactive onboarding: credentials, MCP setup, skills tour |
| `/orq:workspace` | Workspace overview: agents, deployments, prompts, datasets |
| `/orq:traces` | Query and summarize traces with filters |
| `/orq:models` | List available AI models by provider |
| `/orq:analytics` | Usage analytics: requests, cost, tokens, errors |
### Available Skills
Triggered by describing what you need. Claude Code picks the right skill automatically.
| 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 |
## AI Router
Beta
Set the following environment variables before launching Claude Code. Once set, every model call Claude Code makes is automatically routed through the [**Orq.ai AI Router**](/docs/proxy/overview) for the duration of that session.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export ANTHROPIC_BASE_URL="https://my.orq.ai/v3/router/"
export ANTHROPIC_AUTH_TOKEN="$ORQ_API_KEY"
export ANTHROPIC_API_KEY="" # must be set to empty to prevent Claude Code from using the Anthropic API directly
```
Traces are not yet available for Claude Code routed through the **AI Router**.