Operata MCP server tools

The Operata MCP Server exposes nine tools over the Model Context Protocol (MCP). To connect a client and learn how authentication and groups work, start with the MCP overview, then follow Connect Claude, Connect Cursor, or Connect ChatGPT.

The Operata MCP Server is live and ready.However, as we ship new features, the tool surface and configuration may change, guided by the MCP specification and your feedback. Follow the changelog for updates.

Endpoints and authentication

The server offers two endpoints. Use OAuth when a person is connecting, and an API key for machine-to-machine integrations.

Property	OAuth endpoint	API key endpoint
Endpoint	`https://mcp.operata.io/mcp`	`https://api.operata.io/v1/mcp`
Authentication	Operata user session (browser sign-in)	Bearer API key in the `Authorization` header
Group access	Every group your user can reach	The single group the key belongs to
Transport	Server-Sent Events (SSE) / JSON-RPC	Server-Sent Events (SSE) / JSON-RPC
API version	v1	v1
Rate limit	100 requests per minute	100 requests per minute per key

For the full comparison, roles, and how to mint a key, see Choose how to connect and Authentication.

Recommended workflow

The trace tools are schema-driven. Learn what data is available before you query it.

list_groups and switch_group — select the group to query (OAuth sessions; API keys are already fixed to their group).
get_schema — learn the 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 one 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) — your reason for requesting the schema.

Example - exploring the agent_interaction fields in the schema

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

Example - asking how MOS score is calculated

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

list_groups

Lists the groups your authenticated account can access.

Over OAuth, this returns every group your Operata user can reach.
With an API key, it returns only the single group the key belongs to.

Each result includes groupId, groupName, and region. Parameters

None.

Example - listing the groups you can access

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

switch_group

Sets the active group for the session. Every later tool call uses this group unless you override it with a groupId parameter on the call. Parameters

groupId (string, required) — the group to switch to. Must be a group your account can access.

Example - switching to a specific group by ID

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

An API key can only reach the group it was created in. Calling switch_group with any other group on an API-key session returns 403 "API key access is restricted to its own group". Connect over OAuth to work across groups.

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.
groupId (string, optional) — group to query. Defaults to the active group you set with switch_group.

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

Example - listing recent agent-interaction traces

{
  "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, which you can combine 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.
groupId (string, optional) — group to query. Defaults to the active group you set with switch_group.

Example - combining scalar and rate queries over May 2026

{
  "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.
groupId (string, optional) — group to query. Defaults to the active group you set with switch_group.

Example - fetching one trace by ID

{
  "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.
groupId (string, optional) — group to query. Defaults to the active group you set with switch_group.

Insights resolve at the cx.telephony span of a trace. Pass a child span — the cx.interaction.agent span, for example — and you may get 404 "span not found" even though the span exists. Retrieve the trace with traces_get and use the cx.telephony span ID.

Example - getting insights for a span

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

traces_span_logs

Returns paginated logs for a specific span within a trace, such as 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.
groupId (string, optional) — group to query. Defaults to the active group you set with switch_group.

Example - paging through a span's logs

{
  "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 hold string values. Filter with "eq": "true", not boolean true.
You can’t use SpanName 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

Confirm the server is reachable and returning the full tool surface. This example uses the API key endpoint, since it authenticates with a single header. The OAuth endpoint uses an interactive sign-in that your MCP client handles.

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

The response lists all nine tools: get_schema, knowledge, list_groups, switch_group, traces_list, traces_query, traces_get, traces_span_insights, and traces_span_logs. For more curl checks, see Test the server with curl.

MCP overview — authentication, groups, and testing for every client.
Connect Claude — Claude Desktop, Claude Code, and the Claude API.
Connect Cursor — Cursor’s MCP configuration.
Connect ChatGPT — a ChatGPT custom connector over OAuth.
Connect OpenCode — OpenCode’s MCP configuration.
Connect Microsoft Copilot Studio — a shared agent for your team.
Connect GitHub Copilot — VS Code, Visual Studio, JetBrains, and the CLI.
Troubleshoot the MCP server — common failure modes and fixes.
Authentication — the API keys the server uses.
Rate limits — the 100 requests per minute per key limit.

Overview & quickstart

API essentials

Endpoints — Contacts

Endpoints — Logs

Endpoints — Users

Endpoints — Data redaction

Events & webhooks

Streaming & backends

AI & MCP

Endpoints and authentication

Recommended workflow

Tools

get_schema

knowledge

list_groups

switch_group

traces_list

traces_query

traces_get

traces_span_insights

traces_span_logs

Services

Query types

Query construction

Verify

​Endpoints and authentication

​Recommended workflow

​Tools

​get_schema

​knowledge

​list_groups

​switch_group

​traces_list

​traces_query

​traces_get

​traces_span_insights

​traces_span_logs

​Services

​Query types

​Query construction

​Verify

​Related

Endpoints and authentication

Recommended workflow

Tools

get_schema

knowledge

list_groups

switch_group

traces_list

traces_query

traces_get

traces_span_insights

traces_span_logs

Services

Query types

Query construction

Verify

Related