Operata MCP Server

🚧

Preview Release

This is a preview release of the Operata MCP Server. Features and configuration options may change as we refine the implementation based on updates to the specification and customer feedback.

Overview

The Operata MCP Server enables you to query traces, run analytics, and retrieve knowledge from Operata directly within your AI workflow using the Model Context Protocol (MCP). This integration allows AI assistants like Claude, ChatGPT, and developer tools to access your CX observability data with structured, programmatic precision.

What is Model Context Protocol?

Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect to external data sources and tools. Think of MCP like a USB-C port for AI applications - it provides a standardized way for AI models to access the context they need to provide more accurate and relevant responses.

Key Benefits

• Structured data access: Query trace data with precise filters, aggregations, and time ranges
• Full trace retrieval: Fetch complete OpenTelemetry traces with all spans, logs, and insights
• Cross-service analytics: Run scalar, series, table, rate, and facet queries across all service views
• Knowledge integration: Access Operata's knowledge base without leaving your workflow
• Secure authentication: Uses your existing Operata API keys with proper scoping
• Multi-client support: Works with Claude Desktop, ChatGPT, OpenCode, and any MCP-compatible client
• Schema-driven: Self-describing schema tool ensures correct query construction

Available Tools

The Operata MCP Server provides seven tools for accessing your data:

get_schema

Returns the complete data schema including available services, column paths, query types, aggregate functions, and filter operators. Call this tool first to understand what data is available and how to construct queries.

Use cases:

• Discover available column paths for each service
• Understand which aggregate functions are supported
• Learn the correct filter syntax before querying

Parameters:

• query_reason (string, optional): Why the schema is being requested

Example:

{
  "name": "get_schema",
  "arguments": {
    "query_reason": "understanding available fields for agent_interaction"
  }
}

knowledge

Retrieve information from the Operata knowledge base. This tool is useful for understanding Operata features, troubleshooting, and getting contextual help about CX observability concepts.

Use cases:

• "What is MOS score and how is it calculated?"
• "How does Operata integrate with Amazon Connect?"
• "How to troubleshoot poor audio quality"

Parameters:

• query (string, required): Your question about Operata features or concepts

Example:

{
  "name": "knowledge",
  "arguments": {
    "query": "What is MOS score and how is it calculated"
  }
}

traces_list

List and search traces with filtering, sorting, and cursor-based pagination. Returns trace summaries with metadata like duration, span count, and status.

Use cases:

• Browse recent traces sorted by time
• Filter traces by span name (e.g., cx.interaction.agent, cx.ai.conversation)
• Find long-running calls or error traces
• Paginate through large result sets

Parameters:

• startTime (string, required): ISO 8601 UTC start time
• endTime (string, required): ISO 8601 UTC end time
• filters (array, optional): Filter objects with path and operator (eq, gt, lt, etc.)
• sort (string, optional): "asc" or "desc" (default: desc)
• limit (integer, optional): Results per page, 1-1000 (default: 100)
• cursor (object, optional): Pagination cursor from previous response

Example:

{
  "name": "traces_list",
  "arguments": {
    "startTime": "2026-05-01T00:00:00Z",
    "endTime": "2026-06-01T00:00:00Z",
    "filters": [
      { "path": "SpanName", "eq": "cx.interaction.agent" }
    ],
    "sort": "desc",
    "limit": 10
  }
}

Available filter fields: SpanName, ServiceName, StatusCode, SpanKind, Duration

traces_query

Execute analytical queries against Operata trace data. Supports five query types that can be combined in a single request: scalar, series, table, rate, and facet.

Each query must specify a key (unique identifier) and service (one of: agent_interaction, node_interaction, ai_interaction, journey_interaction).

Query types:

Parameters:

• startTime (string, required): ISO 8601 UTC start time
• endTime (string, required): ISO 8601 UTC end time
• queries (object, required): Object containing arrays for each query type

Example (scalar + rate combined):

{
  "name": "traces_query",
  "arguments": {
    "startTime": "2026-05-01T00:00:00Z",
    "endTime": "2026-06-01T00:00:00Z",
    "queries": {
      "scalar": [
        {
          "key": "agent_overview",
          "service": "agent_interaction",
          "aggregates": [
            { "name": "count", "fn": "count", "path": "*" },
            { "name": "avg_mos", "fn": "avg", "path": "Attributes.cx.webrtc.audio.mos_score" },
            { "name": "p90_mos", "fn": "p90", "path": "Attributes.cx.webrtc.audio.mos_score" }
          ]
        }
      ],
      "rate": [
        {
          "key": "quality_rates",
          "service": "agent_interaction",
          "rates": [
            { "name": "poor_mos", "filters": [{ "path": "Attributes.cx.webrtc.audio.mos_score", "lt": 3.0 }] },
            { "name": "high_jitter", "filters": [{ "path": "Attributes.cx.webrtc.audio.jitter_ms", "gt": 50 }] }
          ]
        }
      ]
    }
  }
}

Services:

• agent_interaction: One row per agent WebRTC/telephony session. Fields use Attributes.cx.* paths. Best for call quality, agent performance, WebRTC diagnostics.
• node_interaction: One row per IVR/contact-flow node execution. Fields use Attributes.cx.flow.*. Best for IVR flow analysis and error rates.
• ai_interaction: One row per bot conversation, enriched with agent handoff context. Fields use Attributes.cx.ai.*. Best for AI bot effectiveness and NLU analysis.
• journey_interaction: One row per complete customer journey. Fields use Attributes.* directly. Best for end-to-end CX analysis, transfers, and wait times.

traces_get

Retrieve a single trace by ID in full OpenTelemetry JSON format with all spans and logs.

Use cases:

• Inspect the complete span tree for a specific call
• Review agent, softphone, and WebRTC session details
• Analyze parent-child span relationships

Parameters:

• traceId (string, required): The 32-character hex trace identifier
• includeInternal (boolean, optional): Include internal operata.* spans (default: false)

Example:

{
  "name": "traces_get",
  "arguments": {
    "traceId": "8b1c0813ca3ca75494be82e036177ef1",
    "includeInternal": false
  }
}

traces_span_insights

Get insights (detected issues and anomalies) associated with a specific span within a trace.

Use cases:

• Check if a specific call had quality issues
• Review detected anomalies for an agent session
• Investigate why a call was flagged

Parameters:

• traceId (string, required): The 32-character hex trace identifier
• spanId (string, required): The 16-character hex span identifier

Example:

{
  "name": "traces_span_insights",
  "arguments": {
    "traceId": "8b1c0813ca3ca75494be82e036177ef1",
    "spanId": "89faf69ce53bc085"
  }
}

traces_span_logs

Get paginated logs for a specific span within a trace. Returns softphone logs, CCP events, and other diagnostic log records.

Use cases:

• Review softphone error logs for a problematic call
• Inspect CCP event sequences during a session
• Debug WebRTC connection issues

Parameters:

• traceId (string, required): The 32-character hex trace identifier
• spanId (string, required): The 16-character hex span identifier
• limit (integer, optional): Max log records to return, 1-1000 (default: 50)
• cursor (object, optional): Pagination cursor from previous response

Example:

{
  "name": "traces_span_logs",
  "arguments": {
    "traceId": "8b1c0813ca3ca75494be82e036177ef1",
    "spanId": "89faf69ce53bc085",
    "limit": 100
  }
}

Prerequisites

Before setting up the Operata MCP Server, ensure you have:

• An active Operata subscription
• An Operata API key (see Creating an API Key)
• Claude Desktop, ChatGPT, OpenCode, or another MCP-compatible client

Creating an API Key

To authenticate with the Operata MCP Server, you'll need to create an API key:

1. Log in to your Operata account
2. Navigate to Group Settings > API Management
3. Click Create New Key
4. Give your key a descriptive name (e.g., "MCP Server - Claude Desktop")
5. Copy and securely store the key - you won't be able to see it again

Supported AI Clients

The Operata MCP Server currently supports the following AI clients:

Configuration

Claude Desktop Setup

To configure the Operata MCP Server with Claude Desktop, you'll need to edit your MCP configuration file:

1. Locate your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the Operata MCP Server configuration:

{
  "mcpServers": {
    "operata": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://api.operata.io/v1/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <your_operata_api_key>"
      }
    }
  }
}

3. Replace the placeholder:

   • Replace <your_operata_api_key> with your actual Operata API key

4. Restart Claude Desktop to apply the changes

OpenCode / Cursor Setup

Add to your opencode.json or MCP configuration:

{
  "mcpServers": {
    "operata": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://api.operata.io/v1/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <your_operata_api_key>"
      }
    }
  }
}

Testing the MCP Server

You can verify that the MCP server is working correctly using curl commands before integrating with your AI client.

Security Note

Remember to replace <your_operata_api_key> with your actual API key in all examples below. Never commit API keys to version control.

List Available Tools

Verify the MCP server is responding and see all available tools:

curl -sS -X POST "https://api.operata.io/v1/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <your_operata_api_key>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

Expected response (abbreviated):

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      { "name": "get_schema", "description": "Get the traces data schema..." },
      { "name": "knowledge", "description": "Retrieve facts from the knowledge base..." },
      { "name": "traces_list", "description": "List and search traces with filtering..." },
      { "name": "traces_query", "description": "Execute analytical queries against traces data..." },
      { "name": "traces_get", "description": "Retrieve a single trace by ID..." },
      { "name": "traces_span_insights", "description": "Get insights for a specific span..." },
      { "name": "traces_span_logs", "description": "Get paginated logs for a specific span..." }
    ]
  }
}

Test the Knowledge Tool

Query the Operata knowledge base:

curl -sS -X POST "https://api.operata.io/v1/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <your_operata_api_key>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "knowledge",
      "arguments": {
        "query": "What is MOS score and how is it calculated"
      }
    }
  }'

Test the Schema Tool

Retrieve the query schema:

curl -sS -X POST "https://api.operata.io/v1/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <your_operata_api_key>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "get_schema",
      "arguments": {
        "query_reason": "initial schema discovery"
      }
    }
  }'

Test the Traces Query Tool

Run a scalar aggregation query:

curl -sS -X POST "https://api.operata.io/v1/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <your_operata_api_key>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "traces_query",
      "arguments": {
        "startTime": "2026-05-01T00:00:00Z",
        "endTime": "2026-06-01T00:00:00Z",
        "queries": {
          "scalar": [
            {
              "key": "total_calls",
              "service": "agent_interaction",
              "aggregates": [
                { "name": "count", "fn": "count", "path": "*" }
              ]
            }
          ]
        }
      }
    }
  }'

Using the MCP Server

Once configured, you can interact with the Operata MCP Server through your AI client. The recommended workflow is:

1. Start with get_schema to understand available fields and query structure
2. Use traces_list to browse and filter traces by time range, span name, or duration
3. Use traces_query for analytics: counts, averages, trends, rates, and facets
4. Use traces_get to drill into specific traces for full span detail
5. Use traces_span_insights and traces_span_logs for deep diagnostics on individual spans
6. Use knowledge for documentation and troubleshooting guidance

Example questions for your AI assistant:

• "Show me the average MOS score by queue for the last 7 days"
• "What percentage of calls had poor audio quality (MOS < 3.0) this month?"
• "Get the full trace for trace ID abc123... and summarize what happened"
• "Which agents had the most holds in the past week?"
• "What are the top disconnect reasons for our inbound calls?"
• "Explain how Operata's WebRTC diagnostics work"

Regional Support

The Operata MCP Server uses a unified endpoint for all regions:

• Endpoint: https://api.operata.io/v1/mcp
• Supported Regions: All

Connection Details

The Operata MCP Server uses the following technical specifications:

• Protocol: HTTPS
• Transport: Server-Sent Events (SSE) / JSON-RPC
• Authentication: Bearer token via Authorization header (token value is your API key)
• API Version: v1

Best Practices

Security

• Key Management: Store API keys securely using environment variables or secure vaults
• Key Rotation: Regularly rotate your API keys following your organization's security policies

Performance

• Schema First: Always call get_schema before constructing complex queries to ensure correct field paths
• Time Range Scoping: Use the narrowest time range that meets your needs to reduce response time
• Batch Queries: Combine multiple query types (scalar, series, rate, facet) in a single traces_query call to minimize round-trips
• Rate Limiting: The MCP server is subject to standard Operata API rate limits of 100 requests per minute per API key. Implement appropriate retry logic with exponential backoff if building custom integrations
• Pagination: Use cursor-based pagination for traces_list and traces_span_logs when working with large result sets

Query Construction

• Service Selection: Choose the correct service for your analysis level -- agent_interaction for call quality, journey_interaction for end-to-end CX, ai_interaction for bot analysis, node_interaction for IVR flows
• Column Paths: Path conventions differ by service. Use Attributes.cx.* for agent_interaction, Attributes.* directly for journey_interaction
• Boolean Filters: Fields like had_agent, had_bot, had_queue are stored as strings. Filter with "eq": "true", not boolean true
• SpanName Limitation: SpanName cannot be used in traces_query filters. Use traces_list with a SpanName filter instead

Privacy

• Data Scoping: Ensure your API key is scoped to the appropriate Operata group
• PII Handling: Be mindful of personally identifiable information in queries and responses
• Compliance: Ensure usage aligns with your organization's data privacy policies

Troubleshooting

MCP Server Not Responding

Problem: The MCP server returns connection errors or timeouts.

Solutions:

1. Verify your API key is valid and hasn't expired
2. Check that the endpoint URL is correct: https://api.operata.io/v1/mcp
3. Ensure your network allows HTTPS connections to api.operata.io
4. Verify your key has appropriate permissions

Tools Not Available in AI Client

Problem: The AI client doesn't show or use Operata tools.

Solutions:

1. Restart your AI client after updating the configuration
2. Verify the MCP configuration file syntax is correct (valid JSON)
3. Check the AI client logs for MCP-related errors
4. Ensure mcp-remote is installed: run npx mcp-remote@latest --help to verify

Authentication Errors

Problem: Receiving 401 Unauthorized or 403 Forbidden errors.

Solutions:

1. Regenerate your API key and update the configuration
2. Verify the key is correctly formatted in the Bearer authorization header
3. Check that your API key hasn't been revoked

Query Returns Empty Results

Problem: Data queries return null or empty result sets.

Solutions:

1. Verify your time range contains data -- try expanding to 30 or 60 days
2. Check that your API key is scoped to the correct Operata group
3. Use get_schema to confirm correct column paths for the service you're querying
4. For ai_interaction or node_interaction, confirm bots or IVR flow logging are configured in your environment
5. Use traces_list without filters first to confirm data exists in the time range

Trace or Span Not Found

Problem: traces_get, traces_span_insights, or traces_span_logs returns 404.

Solutions:

1. Verify the trace ID is exactly 32 hex characters
2. Verify the span ID is exactly 16 hex characters
3. Confirm the trace exists by searching with traces_list or traces_query (table query) first
4. Ensure the span belongs to the specified trace

Support and Feedback

We value your feedback to help improve the Operata MCP Server. To provide feedback, share your use cases and feature requests with your Customer Support Manager.