Skip to main content

MCP Integration

Access your Orq.ai workspace directly from Claude Code. Query traces and models using natural language.

AI Gateway  Beta

Route Claude Code’s model calls through the AI Gateway.

​
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

​
Installation

Add the Orq MCP server to Claude Code with a single command: 
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:
export ORQ_API_KEY="your-api-key-here"

​
Verify Installation

Check that the Orq MCP is installed: 
claude mcp list
You should see orq in the list of available MCP servers.

​
What You Can Do

Once integrated, you can ask Claude Code to perform these operations:
  • Get analytics overview for my workspace
  • Show me workspace metrics for the last 7 days
  • Query analytics filtered by deployment ID
  • List all available chat models
  • List all available embedding models
  • Invoke model [model-id] with prompt [message]
  • 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]

​
Usage Examples

​
Query Trace Analytics

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

​
Performance Analysis

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

​
Trace Investigation

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/assistant-plugins marketplace exposes two plugins for Claude Code. Add the marketplace once, then install whichever plugins you need: 
claude plugin marketplace add orq-ai/assistant-plugins
PluginPurpose
orq-mcpStandalone Orq MCP server. Gives Claude access to Orq.ai platform tools (agents, analytics, traces, experiments).
orq-traceAutomatically traces Claude Code sessions to orq.ai: captures sessions, turns, tool calls, and LLM responses as hierarchical OTLP spans.

​
MCP server

claude plugin install orq-mcp@assistant-plugins

​
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. 
claude plugin install orq-trace@assistant-plugins
Set ORQ_API_KEY in your environment so the plugin can ship spans to your workspace. Sessions appear under Traces once the next session starts.

​
AI Gateway

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 Gateway for the duration of that session. 
export ANTHROPIC_BASE_URL="https://api.orq.ai/v3/anthropic"
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
export ANTHROPIC_MODEL="anthropic/claude-sonnet-4-5"  # the anthropic/ prefix is required
Claude Code requests routed through the AI Gateway appear in Traces.