> ## 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.

# Troubleshoot the Operata MCP server

> Fixes for common Operata MCP Server problems: connection errors, missing tools, authentication failures, group access, and empty query results.

Common failure modes for the Operata MCP Server and how to fix them. For setup, start with the [MCP overview](/docs/guides-mcp-intro) or your client's guide.

## The server doesn't respond

1. Check the endpoint URL: `https://mcp.operata.io/mcp` for OAuth, `https://api.operata.io/v1/mcp` for an API key.
2. Confirm your network allows HTTPS to `mcp.operata.io` or `api.operata.io`.
3. **OAuth** — reconnect to refresh an expired session. In Claude Code, run `/mcp`.
4. **API key** — verify the key is valid, not revoked, and has the right permissions.

## Tools don't appear in your client

1. Restart the client after you change its configuration.
2. Check the MCP configuration file is valid JSON.
3. Read the client's logs for MCP errors.
4. Confirm `mcp-remote` runs: `npx mcp-remote@latest --help`.

## Authentication errors (401 or 403)

1. **OAuth** — sessions are short-lived and expire. Reconnect your client for a fresh sign-in (in Claude Code, run `/mcp`).
2. **OAuth** — confirm your user has the **Admin** or **User** role. **Viewer** accounts and **RBAC users** can't use the server.
3. **API key** — regenerate the key, update the configuration, and check the `Authorization: Bearer` header is correct and the key isn't revoked.
4. `403 "API key access is restricted to its own group"` means an API-key session tried to use another group. Connect over OAuth to work across groups.

## A group is missing, or `switch_group` is rejected

1. **API key** — keys only ever see their own group. Connect over OAuth to reach others.
2. **OAuth** — `list_groups` returns only the groups your user is scoped to. Confirm your access in Operata.
3. Confirm your role is **Admin** or **User**, and that you aren't an **RBAC user**.

## A query returns no results

1. Confirm the time range contains data — try widening it to 30 or 60 days.
2. Confirm the active group is correct with `switch_group`, or pass `groupId` on the call.
3. Use `get_schema` to check the column paths for the service you're querying.
4. For `ai_interaction` or `node_interaction`, confirm bots or IVR flow logging are configured.
5. Run `traces_list` with no filters to confirm data exists in the range.

## A trace or span isn't found

1. Confirm the trace ID is exactly 32 hex characters.
2. Confirm the span ID is exactly 16 hex characters.
3. Confirm the trace exists with `traces_list` or a `traces_query` table query first.
4. Confirm the span belongs to the trace.

## Related

* [MCP overview](/docs/guides-mcp-intro) — authentication, groups, and testing for every client.
* [MCP tools reference](/docs/guides-mcp-tools) — every tool, its parameters, and examples.
* [Authentication](/docs/api-authentication) — the API keys the server uses.
* [Rate limits](/docs/api-rate-limits) — the 100 requests per minute per key limit.