Skip to main content
Common failure modes for the Operata MCP Server and how to fix them. For setup, start with the MCP overview 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.