Operata MCP server tools

The Operata MCP Server exposes twelve 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_insights and traces_span_logs — deep diagnostics on a trace and its spans.
knowledge — documentation and troubleshooting guidance.
agent_logs, agent_status, and agent_reported_issues — browser debug logs, presence changes, and agent-reported issues.

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_insights

Returns all insights (detected issues and anomalies) for a trace. Each insight carries the spanId it belongs to, so you can group results by span. Parameters

traceId (string, required) — the 32-character hex trace identifier.
groupId (string, optional) — group to query. Defaults to the active group you set with switch_group.
query_reason (string, optional) — your reason for requesting the insights.

Example - getting insights for a trace

{
  "name": "traces_insights",
  "arguments": {
    "traceId": "8b1c0813ca3ca75494be82e036177ef1"
  }
}

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

agent_logs

Fetches raw CCP and softphone debug logs collected from the agent’s browser, covering levels TRACE through ERROR across components such as ccp, softphone, and webrtc-sdk. Query by time window, agent, or contact ID, then narrow by component, level, or free text to troubleshoot media, connection, and CCP errors. Parameters

startTime (string, optional) — ISO 8601 UTC start time. Required with endTime unless you provide agent or contactId.
endTime (string, optional) — ISO 8601 UTC end time. Required with startTime unless you provide agent or contactId.
agent (string, optional) — agent email or username. Provide this, a timeframe, or a contactId.
contactId (string, optional) — the contact or interaction ID (cx.interaction.id). Pivot from a trace or a reported issue.
filters (array, optional) — AND-combined filter objects, each a field, op, and value.
limit (integer, optional) — results per page, 1–2000. Default 500.
cursor (object, optional) — pagination cursor from a previous response.
sort (string, optional) — sort by time, "asc" or "desc". Default "desc".
groupId (string, optional) — group to query. Defaults to the active group you set with switch_group.
query_reason (string, optional) — your reason for querying agent logs.

Available filter fields: component, level, text (full-text), agent, contact_id.

total stops counting at 10,000. If it comes back as exactly 10,000, the query is too broad — narrow it.

Example - fetching ERROR-level logs for a specific contact

{
  "name": "agent_logs",
  "arguments": {
    "contactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "filters": [
      { "field": "level", "op": "eq", "value": "ERROR" }
    ],
    "limit": 100
  }
}

agent_status

Searches agent status and presence changes from the softphone, such as Available, Busy, On Break, After Call Work, and custom auxiliary states. Query by time window or agent, then narrow by status value or contact ID. Parameters

startTime (string, optional) — ISO 8601 UTC start time. Required with endTime unless you provide agent.
endTime (string, optional) — ISO 8601 UTC end time. Required with startTime unless you provide agent.
agent (string, optional) — agent email or username. Provide this or a timeframe.
filters (array, optional) — AND-combined filter objects, each a field, op, and value.
limit (integer, optional) — results per page, 1–1000. Default 100.
cursor (object, optional) — pagination cursor from a previous response.
sort (string, optional) — sort by timestamp, "asc" or "desc". Default "desc".
groupId (string, optional) — group to query. Defaults to the active group you set with switch_group.
query_reason (string, optional) — your reason for querying agent status.

Available filter fields: status, contact_id.

Example - checking an agent's status changes over the last hour

{
  "name": "agent_status",
  "arguments": {
    "agent": "jane.doe@example.com",
    "startTime": "2026-05-01T09:00:00Z",
    "endTime": "2026-05-01T10:00:00Z",
    "sort": "asc"
  }
}

agent_reported_issues

Searches agent-reported issues, such as audio, softphone, or connectivity problems flagged during or after a call. Query by time window or agent, then narrow by category, severity, scenario, cause, error type, browser, or contact ID. Parameters

startTime (string, optional) — ISO 8601 UTC start time. Required with endTime unless you provide agent.
endTime (string, optional) — ISO 8601 UTC end time. Required with startTime unless you provide agent.
agent (string, optional) — agent email or username. Provide this or a timeframe.
filters (array, optional) — AND-combined filter objects, each a field, op, and value.
limit (integer, optional) — results per page, 1–1000. Default 100.
cursor (object, optional) — pagination cursor from a previous response.
sort (string, optional) — sort by timestamp, "asc" or "desc". Default "desc".
groupId (string, optional) — group to query. Defaults to the active group you set with switch_group.
query_reason (string, optional) — your reason for querying reported issues.

Available filter fields: category, severity, scenario, cause, contact_id, error_type, browser_name.

Example - finding audio-related issues reported in the last 24 hours

{
  "name": "agent_reported_issues",
  "arguments": {
    "startTime": "2026-05-14T00:00:00Z",
    "endTime": "2026-05-15T00:00:00Z",
    "filters": [
      { "field": "category", "op": "eq", "value": "audio" }
    ],
    "limit": 50
  }
}

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 twelve tools: get_schema, knowledge, list_groups, switch_group, traces_list, traces_query, traces_get, traces_insights, traces_span_logs, agent_logs, agent_status, and agent_reported_issues. 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.

​Endpoints and authentication

​Recommended workflow

​Tools

​get_schema

​knowledge

​list_groups

​switch_group

​traces_list

​traces_query

​traces_get

​traces_insights

​traces_span_logs

​agent_logs

​agent_status

​agent_reported_issues

​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_insights

traces_span_logs

agent_logs

agent_status

agent_reported_issues

Services

Query types

Query construction

Verify

Related