Operata MCP server tools

The Operata MCP Server exposes seven tools over the Model Context Protocol (MCP). To connect a client first, see Connect Claude, Connect Cursor, or Connect ChatGPT.

The Operata MCP Server is in preview. The tool surface may change as the implementation tracks the MCP specification and customer feedback. Follow the changelog for updates.

Endpoint and authentication

Property	Value
Endpoint	`https://api.operata.io/v1/mcp`
Transport	Server-Sent Events (SSE) / JSON-RPC
Authentication	Bearer token in the `Authorization` header — the token value is your Operata API token
API version	v1
Rate limit	100 requests per minute per token

The MCP server uses the same Operata API tokens as the REST API. See Authentication to mint one, and Rate limits for throttling behavior.

Recommended workflow

The trace tools are schema-driven. Discover the shape of the data before you query it.

get_schema — learn the available services, column paths, query types, aggregate functions, and filter operators.
traces_list — browse and filter traces by time range, span name, or duration.
traces_query — run analytics: counts, averages, trends, rates, and facets.
traces_get — drill into a single trace for the full span tree.
traces_span_insights and traces_span_logs — deep diagnostics on an individual span.
knowledge — documentation and troubleshooting guidance.

Tools

get_schema

Returns the complete data schema: available services, column paths, query types, aggregate functions, and filter operators. Call this tool first so the AI client constructs valid queries. Parameters

query_reason (string, optional) — why the schema is being requested.

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

knowledge

Retrieves information from the Operata knowledge base — Operata features, CX observability concepts, and troubleshooting guidance. Parameters

query (string, required) — your question about Operata features or concepts.

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

traces_list

Lists and searches traces with filtering, sorting, and cursor-based pagination. Returns trace summaries with metadata such as duration, span count, and status. Parameters

startTime (string, required) — ISO 8601 UTC start time.
endTime (string, required) — ISO 8601 UTC end time.
filters (array, optional) — filter objects, each a path plus an operator (eq, gt, lt, and so on).
sort (string, optional) — "asc" or "desc". Default "desc".
limit (integer, optional) — results per page, 1–1000. Default 100.
cursor (object, optional) — pagination cursor from a previous response.

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

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

traces_query

Executes analytical queries against trace data. Supports five query types that can be combined in a single request. Each query specifies a key (a unique identifier) and a service. Parameters

startTime (string, required) — ISO 8601 UTC start time.
endTime (string, required) — ISO 8601 UTC end time.
queries (object, required) — an object containing arrays for each query type.

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

traces_get

Retrieves a single trace by ID in full OpenTelemetry JSON, with all spans and logs. Parameters

traceId (string, required) — the 32-character hex trace identifier.
includeInternal (boolean, optional) — include internal operata.* spans. Default false.

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

traces_span_insights

Returns the insights — detected issues and anomalies — associated with a specific span within a trace. Parameters

traceId (string, required) — the 32-character hex trace identifier.
spanId (string, required) — the 16-character hex span identifier.

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

traces_span_logs

Returns paginated logs for a specific span within a trace — softphone logs, CCP events, and other diagnostic records. 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, 1–1000. Default 50.
cursor (object, optional) — pagination cursor from a previous response.

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

Services

traces_query and the schema operate against four services. Each is one row per interaction at a different level of the customer journey.

Service	Granularity	Path convention	Best for
`agent_interaction`	One agent WebRTC/telephony session	`Attributes.cx.*`	Call quality, agent performance, WebRTC diagnostics
`node_interaction`	One IVR/contact-flow node execution	`Attributes.cx.flow.*`	IVR flow analysis and error rates
`ai_interaction`	One bot conversation, with agent-handoff context	`Attributes.cx.ai.*`	AI bot effectiveness and NLU analysis
`journey_interaction`	One complete customer journey	`Attributes.*`	End-to-end CX, transfers, and wait times

Query types

A single traces_query request can combine any of these types.

Type	Purpose	Key fields
Scalar	Aggregated values (count, avg, p90, and so on) with optional grouping	`aggregates`, `grouping`, `filters`
Series	Time-bucketed aggregations for trends	`aggregates`, `interval` (seconds)
Table	Raw row data with selected columns	`columns`, `limit`, `orders`
Rate	Occurrence rates (for example, poor-MOS rate)	`rates` with filter definitions
Facet	Unique values for a field, with counts	`path`, `limit`

Query construction

These constraints trip up generated queries most often:

Service selection drives the path convention. Use Attributes.cx.* for agent_interaction; use Attributes.* directly for journey_interaction.
Boolean fields such as had_agent, had_bot, and had_queue are stored as strings. Filter with "eq": "true", not boolean true.
SpanName cannot be used in traces_query filters. Use traces_list with a SpanName filter instead.

Call get_schema before building a complex query. Scope startTime/endTime to the narrowest range that meets your need, and combine query types in one traces_query call to minimize round-trips. Use cursor-based pagination on traces_list and traces_span_logs for large result sets.

Verify

List the available tools to confirm the server is reachable and returning the full tool surface:

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 $OPERATA_API_TOKEN" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} }'

The response lists all seven tools: get_schema, knowledge, traces_list, traces_query, traces_get, traces_span_insights, and traces_span_logs.

Connect Claude to the Operata MCP server — Claude Desktop, Claude Code, and the Claude API.
Connect Cursor to the Operata MCP server — Cursor’s MCP configuration.
Connect ChatGPT to the Operata MCP server — the ChatGPT integration roadmap.
Authentication — the API tokens the MCP server uses.
Rate limits — the 100 requests per minute per token limit.

Overview & quickstart

API essentials

Endpoints — Contacts

Endpoints — Logs

Endpoints — Users

Endpoints — Data redaction

Events & webhooks

Streaming & backends

AI & MCP

Endpoint and authentication

Recommended workflow

Tools

get_schema

knowledge

traces_list

traces_query

traces_get

traces_span_insights

traces_span_logs

Services

Query types

Query construction

Verify

​Endpoint and authentication

​Recommended workflow

​Tools

​get_schema

​knowledge

​traces_list

​traces_query

​traces_get

​traces_span_insights

​traces_span_logs

​Services

​Query types

​Query construction

​Verify

​Related

Endpoint and authentication

Recommended workflow

Tools

get_schema

knowledge

traces_list

traces_query

traces_get

traces_span_insights

traces_span_logs

Services

Query types

Query construction

Verify

Related