Operata MCP server

The Operata MCP Server lets an AI client query your traces, run analytics, and read the Operata knowledge base over the Model Context Protocol (MCP). Ask Claude, ChatGPT, Cursor, or another MCP client a question in plain language, and it calls the right Operata tool and answers from your account. This page covers what every client shares: how to authenticate, which clients are supported, how groups and regions work, and how to test the server. Each client also has its own short setup guide:

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.
MCP tools reference — every tool, its parameters, and examples.

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.

What is the Model Context Protocol?

MCP is an open standard that connects AI assistants to external data and tools. It gives an AI model a consistent way to reach the context it needs, so answers come from your data instead of guesswork.

What you can do

Query traces with precise filters, aggregations, and time ranges.
Retrieve full OpenTelemetry traces with every span, log, and insight.
Run cross-service analytics — scalar, series, table, rate, and facet queries.
Search the knowledge base without leaving your AI client.
Work across your groups, with every query scoped to the group you choose.

Choose how to connect

The server offers two endpoints. Pick one based on whether a person or a machine is connecting.

	OAuth endpoint (recommended)	API key endpoint
URL	`https://mcp.operata.io/mcp`	`https://api.operata.io/v1/mcp`
Authenticates as	Your Operata user, in a short-lived session	An API key, long-lived
Best for	A person using an AI client	Machine-to-machine integrations
Group access	Every group your user can reach	The single group the key belongs to
SSO	Supported	Not applicable

Use OAuth when a person is at the keyboard. Use an API key only for automated integrations that run without anyone present.

OAuth

OAuth signs you in as your Operata user. The session is short-lived, scoped to your role, and can reach any group your account has access to. SSO sign-in works. There’s 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

An API key is a long-lived bearer credential for automated, non-interactive use. It authenticates as an API user with full API privileges and is restricted to the single group it was created in, so it can’t list or switch to other groups. To create one, sign in to Operata, open Group Settings → API Management, and click Create New Key. Give it a descriptive name such as MCP Server — CI pipeline, then copy and store the value. The console won’t show it again. For more on Operata API keys, see Authentication.

Before you start

An active Operata subscription.
Credentials for your chosen endpoint:
- OAuth — an Operata user with the Admin or User role. Viewer accounts and RBAC users can’t use the MCP Server.
- API key — an Operata API key.
A supported AI client, installed and signed in.

Supported clients

Client	Authentication	How you configure it
Claude Desktop	OAuth or API key	MCP configuration file
Claude Code	OAuth or API key	CLI (`claude mcp add`)
ChatGPT	OAuth	Connector settings
OpenCode	OAuth or API key	MCP configuration file
Cursor	OAuth or API key	MCP configuration file

Groups and regions

Every query runs against one group. How you select it depends on how you connected.

OAuth — list the groups your account can reach with list_groups, then set the active one with switch_group. Override it on any single call with a groupId parameter.
API key — the key is fixed to its own group, so there’s nothing to select. switch_group to any other group returns 403 "API key access is restricted to its own group".

The endpoints serve all regions. Each group is hosted in a specific region (for example ap-southeast-2 or us-east-2), and list_groups returns the region for each group you can reach.

Recommended workflow

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

Select your group — list_groups, then switch_group (OAuth only; API-key sessions 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.

For the full tool surface, see the MCP tools reference.

Questions to ask your AI client

“Show me the average MOS score by queue for the last 7 days.”
“What percentage of calls had poor audio quality (MOS below 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.”

Test the server with curl

Before wiring up a client, confirm the server responds. These examples use the API key endpoint, since it authenticates with a single header. The OAuth endpoint uses an interactive browser sign-in that your MCP client handles, not curl. Replace $OPERATA_API_KEY with your key. List the 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 $OPERATA_API_KEY" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} }'

Query the 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 $OPERATA_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "knowledge",
      "arguments": { "query": "What is MOS score and how is it calculated" }
    }
  }'

Run a scalar aggregation:

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": 3,
    "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": "*" }]
            }
          ]
        }
      }
    }
  }'

Best practices

Security

Prefer OAuth for people. OAuth sessions follow the signing-in user’s role and groups, so access stays least-privilege. API keys carry full API privileges — reserve them for machine-to-machine use.
Store API keys in environment variables or a secrets vault, never in shared config.
Rotate keys on your organization’s schedule.
Confirm the active group with switch_group, or set groupId per call, before you query.

Performance

Call get_schema first so queries use valid field paths.
Scope the time range to the narrowest window that answers your question.
Batch query types — combine scalar, series, rate, and facet in one traces_query call to cut round-trips.
Paginate traces_list and traces_span_logs with the cursor for large result sets.
Respect the rate limit of 100 requests per minute per key. Retry with exponential backoff in custom integrations.

Privacy

Scope to the right group before you query, so you never read another group’s data.
Watch for PII in queries and responses.
Follow your organization’s data privacy policies.

Support and feedback

Share your use cases and feature requests with your Customer Support Manager. Your feedback shapes what ships next.

Connect Claude to the Operata MCP server
Connect Cursor to the Operata MCP server
Connect ChatGPT to the Operata MCP server
Connect OpenCode to the Operata MCP server
MCP tools reference
Troubleshoot the MCP server — common failure modes and fixes.
Authentication — mint 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

What is the Model Context Protocol?

What you can do

Choose how to connect

OAuth

API key

Before you start

Supported clients

Groups and regions

Recommended workflow

Questions to ask your AI client

Test the server with curl

Best practices

Security

Performance

Privacy

Support and feedback

​What is the Model Context Protocol?

​What you can do

​Choose how to connect

​OAuth

​API key

​Before you start

​Supported clients

​Groups and regions

​Recommended workflow

​Questions to ask your AI client

​Test the server with curl

​Best practices

​Security

​Performance

​Privacy

​Support and feedback

​Related

What is the Model Context Protocol?

What you can do

Choose how to connect

OAuth

API key

Before you start

Supported clients

Groups and regions

Recommended workflow

Questions to ask your AI client

Test the server with curl

Best practices

Security

Performance

Privacy

Support and feedback

Related