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
• Flexible authentication: Sign in with your Operata user credentials over OAuth (recommended), or use a long-lived API key for machine-to-machine integrations
• Group-aware: Discover and switch between the groups your account can access, with every query scoped to the active group
• Multi-client support: Works with Claude Desktop, Claude Code, ChatGPT, OpenCode, Cursor, and any MCP-compatible client
• Schema-driven: Self-describing schema tool ensures correct query construction

Available Tools

The Operata MCP Server provides nine 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"
  }
}

list_groups

List the groups your authenticated account can access. When signed in over OAuth, this returns every group your Operata user is scoped to; when using an API key, it returns only the single group the key belongs to.

Use cases:

• Discover which groups you can query
• Find the groupId to pass to switch_group or to individual tools
• Confirm the region a group is hosted in

Parameters:

• None

Example:

{
  "name": "list_groups",
  "arguments": {}
}

Each result includes groupId, groupName, and region.

switch_group

Set the active group for the current session. All subsequent tool calls use this group unless you override it with an explicit groupId parameter on the call.

Use cases:

• Select a group before running queries (OAuth sessions)
• Move between groups without re-authenticating

Parameters:

• groupId (string, required): The group ID to switch to. Must be a group your account can access.

Example:

{
  "name": "switch_group",
  "arguments": {
    "groupId": "5bbbd17a-fd70-45ad-a048-c4674035f406"
  }
}

Note

API keys are restricted to their own group. Calling switch_group with any other group on an API-key session returns 403 "API key access is restricted to its own group". Use the OAuth endpoint to work across multiple groups.

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
• groupId (string, optional): Group to query against. Defaults to the active group set via switch_group

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
• groupId (string, optional): Group to query against. Defaults to the active group set via switch_group

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)
• groupId (string, optional): Group to query against. Defaults to the active group set via switch_group

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
• groupId (string, optional): Group to query against. Defaults to the active group set via switch_group

Tip

Insights resolve at the cx.telephony span of a trace. If you pass a child span (for example the cx.interaction.agent span) you may receive 404 "span not found" even though the span exists — retrieve the trace with traces_get and use the cx.telephony span ID.

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
• groupId (string, optional): Group to query against. Defaults to the active group set via switch_group

Example:

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

Authentication and Endpoints

The Operata MCP Server offers two endpoints. Choose based on who (or what) is connecting:

OAuth (recommended)

OAuth signs you in as your Operata user. Your session is short-lived, scoped to your role, and can reach any group your account has access to — switch between them with switch_group. SSO sign-in is supported.

Requirements:

• An Operata user with the Admin or User role. Viewer accounts cannot use the MCP Server.
• RBAC users are not supported.

There is nothing to create ahead of time — the first time your client connects to https://mcp.operata.io/mcp it opens an Operata sign-in in your browser to authorize the session.

API key (machine-to-machine)

API keys are long-lived bearer credentials for automated, non-interactive use. An API key authenticates as an API user with full API privileges and is restricted to the single group it was created in — it cannot list or switch to other groups.

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 - CI pipeline")
5. Copy and securely store the key - you won't be able to see it again

Prerequisites

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

• An active Operata subscription
• Credentials for your chosen endpoint:
  • OAuth — an Operata user account with the Admin or User role, or
  • API key — an Operata API key (see API key)
• Claude Desktop, Claude Code, ChatGPT, OpenCode, Cursor, or another MCP-compatible client

Supported AI Clients

The Operata MCP Server currently supports the following AI clients:

Configuration

OAuth is the recommended way to connect. Use an API key only for machine-to-machine integrations that run without a human present.

After connecting over OAuth, select the group you want to work in with list_groups followed by switch_group (or pass groupId on individual calls). API-key sessions are already scoped to their single group.

Option A — OAuth (recommended)

Point your client at the OAuth endpoint. No header or stored secret is required — mcp-remote runs the browser sign-in flow on first connect and caches the session.

Claude Desktop / OpenCode / Cursor

1. Locate your client's MCP configuration file:

   • Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
   • Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
   • OpenCode / Cursor: opencode.json or your client's MCP configuration

2. Add the Operata MCP Server configuration:

{
  "mcpServers": {
    "operata": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://mcp.operata.io/mcp"
      ]
    }
  }
}

3. Restart your client. On first use a browser window opens to sign in to Operata and authorize the session.

Claude Code (CLI)

Add the server with the OAuth endpoint:

claude mcp add --transport http operata https://mcp.operata.io/mcp

Then run /mcp inside Claude Code and follow the prompt to authenticate. Use /mcp again at any time to reconnect or re-authenticate.

Option B — API key (machine-to-machine)

Use the API endpoint with a long-lived key. Remember the key can only access the single group it was created in.

Claude Desktop / OpenCode / Cursor

{
  "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>"
      }
    }
  }
}

Replace <your_operata_api_key> with your actual Operata API key, then restart your client.

Claude Code (CLI)

claude mcp add --transport http operata https://api.operata.io/v1/mcp \
  --header "Authorization: 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.

Note

The curl examples below use the API endpoint with a bearer API key, since it authenticates with a single header. The OAuth endpoint (https://mcp.operata.io/mcp) uses an interactive browser sign-in that is handled by your MCP client rather than by curl.
Remember to replace <your_operata_api_key> with your actual API key in all examples below.

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": "list_groups", "description": "List groups the authenticated user can access..." },
      { "name": "switch_group", "description": "Set the active group for this session..." },
      { "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. Select your group with list_groups then switch_group (OAuth sessions). API-key sessions are already locked to their group, so you can skip this step.
2. Start with get_schema to understand available fields and query structure
3. Use traces_list to browse and filter traces by time range, span name, or duration
4. Use traces_query for analytics: counts, averages, trends, rates, and facets
5. Use traces_get to drill into specific traces for full span detail
6. Use traces_span_insights and traces_span_logs for deep diagnostics on individual spans
7. 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 unified endpoints that serve all regions:

• OAuth endpoint: https://mcp.operata.io/mcp
• API endpoint: https://api.operata.io/v1/mcp
• Supported Regions: All

Individual groups are hosted in a specific region (for example ap-southeast-2 or us-east-2). The region of each group you can access is returned by list_groups.

Connection Details

The Operata MCP Server uses the following technical specifications:

• Protocol: HTTPS
• Transport: Server-Sent Events (SSE) / JSON-RPC
• Authentication: OAuth user session (mcp.operata.io) or bearer API key via Authorization header (api.operata.io)
• API Version: v1 (API endpoint)

Best Practices

Security

• Prefer OAuth for people: OAuth sessions are scoped to the signing-in user's role and groups, so access follows least privilege. API keys authenticate as an API user with full API privileges — reserve them for machine-to-machine integrations.
• 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
• Group Scoping: Confirm the active group (switch_group) or per-call groupId before running queries, so you operate against the intended group

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 you are operating against the intended group — set it with switch_group (OAuth), or rely on the single group an API key is scoped to
• 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. Check that the endpoint URL is correct: https://mcp.operata.io/mcp (OAuth) or https://api.operata.io/v1/mcp (API key)
2. Ensure your network allows HTTPS connections to mcp.operata.io and/or api.operata.io
3. OAuth: reconnect to refresh an expired session (in Claude Code, run /mcp)
4. API key: verify the key is valid, hasn't been revoked, and 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. OAuth: Re-authenticate — sessions are short-lived and expire. Reconnect your client (in Claude Code, run /mcp) to start a fresh sign-in.
2. OAuth: Confirm your Operata user has the Admin or User role. Viewer accounts and RBAC users cannot use the MCP Server.
3. API key: Regenerate your key and update the configuration; verify it is correctly formatted in the Bearer authorization header and hasn't been revoked.
4. 403 "API key access is restricted to its own group" means an API-key session tried to use a group other than the key's own. Use the OAuth endpoint to work across multiple groups.

Can't See or Switch to a Group

Problem: A group you expect is missing from list_groups, or switch_group is rejected.

Solutions:

1. API key: keys only ever see their own group. To reach other groups, connect over the OAuth endpoint.
2. OAuth: list_groups returns only the groups your user is scoped to — confirm your account has access to the group in Operata.
3. Verify your role is Admin or User (not Viewer), and that you are not an RBAC user.

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. Confirm the active group is correct — set it with switch_group or pass groupId on the call (API-key sessions are fixed to their own 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.