> ## Documentation Index
> Fetch the complete documentation index at: https://docs.operata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Operata MCP server tools

> Reference for the seven tools the Operata MCP Server exposes — schema discovery, trace search, analytical queries, full-trace retrieval, and span-level diagnostics.

The Operata MCP Server exposes seven tools over the Model Context Protocol (MCP).
To connect a client first, see
[Connect Claude](/docs/guides-mcp-claude),
[Connect Cursor](/docs/guides-mcp-cursor), or
[Connect ChatGPT](/docs/guides-mcp-chatgpt).

<Info>
  The Operata MCP Server is in preview. The tool surface may change as
  the implementation tracks the [MCP specification](https://modelcontextprotocol.io)
  and customer feedback. Follow the [changelog](/docs/changelog) for updates.
</Info>

## 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](/docs/api-authentication) to mint one, and
[Rate limits](/docs/api-rate-limits) for throttling behavior.

## Recommended workflow

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

1. **`get_schema`** — learn the available services, column paths, query
   types, aggregate functions, and filter operators.
2. **`traces_list`** — browse and filter traces by time range, span
   name, or duration.
3. **`traces_query`** — run analytics: counts, averages, trends, rates,
   and facets.
4. **`traces_get`** — drill into a single trace for the full span tree.
5. **`traces_span_insights`** and **`traces_span_logs`** — deep
   diagnostics on an individual span.
6. **`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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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`.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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`.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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

<Note>
  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.
</Note>

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:

```bash theme={null}
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`.

## Related

* [Connect Claude to the Operata MCP server](/docs/guides-mcp-claude) — Claude Desktop, Claude Code, and the Claude API.
* [Connect Cursor to the Operata MCP server](/docs/guides-mcp-cursor) — Cursor's MCP configuration.
* [Connect ChatGPT to the Operata MCP server](/docs/guides-mcp-chatgpt) — the ChatGPT integration roadmap.
* [Authentication](/docs/api-authentication) — the API tokens the MCP server uses.
* [Rate limits](/docs/api-rate-limits) — the 100 requests per minute per token limit.