> ## 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 > Connect an AI client to the Operata MCP Server to query your live traces, run analytics, and search the knowledge base over the Model Context Protocol. 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](/docs/guides-mcp-claude) — Claude Desktop, Claude Code, and the Claude API. * [Connect Cursor](/docs/guides-mcp-cursor) — Cursor's MCP configuration. * [Connect ChatGPT](/docs/guides-mcp-chatgpt) — a ChatGPT custom connector over OAuth. * [Connect OpenCode](/docs/guides-mcp-opencode) — OpenCode's MCP configuration. * [MCP tools reference](/docs/guides-mcp-tools) — 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](https://modelcontextprotocol.io) and your feedback. Follow the [changelog](/docs/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](/docs/api-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](/docs/api-authentication). * 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. 1. **Select your group** — `list_groups`, then `switch_group` (OAuth only; API-key sessions are already fixed to their group). 2. **`get_schema`** — learn the services, column paths, query types, aggregate functions, and filter operators. 3. **`traces_list`** — browse and filter traces by time range, span name, or duration. 4. **`traces_query`** — run analytics: counts, averages, trends, rates, and facets. 5. **`traces_get`** — drill into a single trace for the full span tree. 6. **`traces_span_insights`** and **`traces_span_logs`** — deep diagnostics on one span. 7. **`knowledge`** — documentation and troubleshooting guidance. For the full tool surface, see the [MCP tools reference](/docs/guides-mcp-tools). ### 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:** ```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_KEY" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} }' ``` **Query the knowledge base:** ```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_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:** ```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_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. ## Related * [Connect Claude to the Operata MCP server](/docs/guides-mcp-claude) * [Connect Cursor to the Operata MCP server](/docs/guides-mcp-cursor) * [Connect ChatGPT to the Operata MCP server](/docs/guides-mcp-chatgpt) * [Connect OpenCode to the Operata MCP server](/docs/guides-mcp-opencode) * [MCP tools reference](/docs/guides-mcp-tools) * [Troubleshoot the MCP server](/docs/guides-mcp-troubleshooting) — common failure modes and fixes. * [Authentication](/docs/api-authentication) — mint the API keys the server uses. * [Rate limits](/docs/api-rate-limits) — the 100 requests per minute per key limit.