Operata MCP Server (Preview)

Overview

The Operata MCP Server enables you to query insights and data from Operata directly within your AI workflow using the Model Context Protocol (MCP). This integration allows AI assistants like Claude and ChatGPT to access your CX observability data, run queries, and retrieve knowledge base information in real-time.

📘
Preview Release
This is an Preview Release of the Operata MCP Server. Features and configuration options may change as we refine the implementation based on customer feedback.

What is Model Context Protocol?

Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect to external data sources and tools. Think of MCP like a USB-C port for AI applications - it provides a standardized way for AI models to access the context they need to provide more accurate and relevant responses.

Key Benefits

Real-time data access: Query your Operata trace data directly from your AI assistant
Knowledge integration: Access Operata's knowledge base without leaving your workflow
Secure authentication: Uses your existing Operata API tokens with proper scoping
Multi-client support: Works with Claude Desktop and ChatGPT (with more clients coming)
Natural language queries: Ask questions in plain language and get structured data back

Available Tools

The Operata MCP Server provides two powerful tools for accessing your data:

query

Query your Operata trace data using natural language. The tool returns data in any text format including natural language responses, CSV, JSON, or formatted tables.

Use cases:

"How many traces were recorded in the last 30 days?"
"Show me error rates by agent for this week"
"What's the average call duration for the past month?"
"List the top 10 agents by call volume"

Parameters:

query (string, required): Your question or data request in natural language

Example:

{
  "name": "query",
  "arguments": {
    "query": "number of traces in last 30 days"
  }
}

knowledge

Retrieve information from the Operata knowledge base. This tool is useful for understanding Operata features, troubleshooting, and getting contextual help.

Use cases:

"Explain Operata CX Risk in one sentence"
"How do I set up data privacy controls?"
"What are the supported browsers for the Agent Experience Collector?"

Parameters:

query (string, required): Your question about Operata features or concepts

Example:

{
  "name": "knowledge",
  "arguments": {
    "query": "Explain Operata CX Risk in one sentence"
  }
}

Prerequisites

Before setting up the Operata MCP Server, ensure you have:

An active Operata subscription
An Operata API token (see Creating an API Token)
Claude Desktop or ChatGPT with MCP support

Creating an API Token

To authenticate with the Operata MCP Server, you'll need to create an API token:

Log in to your Operata account
Navigate to Settings > API Tokens
Click Create New Token
Give your token a descriptive name (e.g., "MCP Server - Claude Desktop")
Copy and securely store the token - you won't be able to see it again

Supported AI Clients

The Operata MCP Server currently supports the following AI clients:

Client	Status	Configuration Method
Claude Desktop	Supported	MCP configuration file
ChatGPT	Coming Soon	OAuth integration planned

Configuration

Claude Desktop Setup

To configure the Operata MCP Server with Claude Desktop, you'll need to edit your MCP configuration file:

Locate your Claude Desktop configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the Operata MCP Server configuration:

{
  "mcpServers": {
    "operata": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://api.operata.io/v1/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <your_operata_api_token>"
      }
    }
  }
}

Replace the placeholder:
- Replace <your_operata_api_token> with your actual Operata API token
Restart Claude Desktop to apply the changes

ChatGPT Configuration (Coming Soon)

OAuth-based authentication for ChatGPT is planned for a future release. The integration will use Operata usernames authenticated via Auth0.

For more details on the OAuth implementation, see the MCP Authorization Specification.

Testing the MCP Server

You can verify that the MCP server is working correctly using curl commands before integrating with your AI client.

🔒
Security Note
Remember to replace <your_operata_api_token> with your actual API token in all examples below. Never commit API tokens to version control.

List Available Tools

Verify the MCP server is responding and see all 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 <your_operata_api_token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

Expected response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "query",
        "description": "Query Operata trace data using natural language",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "Your question or data request in natural language"
            }
          },
          "required": ["query"]
        }
      },
      {
        "name": "knowledge",
        "description": "Retrieve information from the Operata knowledge base",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "Your question about Operata features or concepts"
            }
          },
          "required": ["query"]
        }
      }
    ]
  }
}

Test the Knowledge Tool

Query the Operata 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 <your_operata_api_token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "knowledge",
      "arguments": {
        "query": "Explain Operata CX Risk in one sentence"
      }
    }
  }'

Expected response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Operata CX Risk is a metric that quantifies the likelihood and potential impact of customer experience issues across your contact center operations."
      }
    ]
  }
}

Test the Query Tool

Run a data query:

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 <your_operata_api_token>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "query",
      "arguments": {
        "query": "number of traces in last 30 days"
      }
    }
  }'

Expected response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "In the last 30 days, there were 1,247,583 traces recorded in your Operata instance."
      }
    ]
  }
}

Using the MCP Server

Once configured, you can start using the Operata MCP Server directly from your AI client.

After setting up the MCP server in Claude Desktop, you can ask questions like:

"Can you check how many traces we've had in the last week?"
"Show me the error rate trend for the past 30 days"
"What are the top issues affecting call quality this month?"
"Explain how Operata's headset monitoring works"

Claude will automatically use the appropriate MCP tool (query or knowledge) to fetch the information and provide a natural language response with the data.

Regional Support

The Operata MCP Server uses a unified endpoint for all regions:

Endpoint: https://api.operata.io/v1/mcp
Supported Regions: All

Connection Details

The Operata MCP Server uses the following technical specifications:

Protocol: HTTPS
Transport: Server-Sent Events (SSE) / JSON-RPC
Authentication: Bearer token via Authorization header
API Version: v1

Best Practices

Security

Token Management: Store API tokens securely using environment variables or secure vaults
Token Rotation: Regularly rotate your API tokens following your organization's security policies
Least Privilege: Create tokens with minimal necessary permissions for your use case
Monitoring: Review API usage logs regularly to detect unauthorized access

Performance

Query Optimization: Be specific in your queries to reduce response time and data transfer
Rate Limiting: The MCP server is subject to standard Operata API rate limits of 100 requests per minute per API token. Implement appropriate retry logic with exponential backoff if building custom integrations
Caching: Consider caching frequently accessed knowledge base queries

Privacy

Data Scoping: Ensure your API token is scoped to the appropriate Operata group
PII Handling: Be mindful of personally identifiable information in queries and responses
Compliance: Ensure usage aligns with your organization's data privacy policies

Troubleshooting

MCP Server Not Responding

Problem: The MCP server returns connection errors or timeouts.

Solutions:

Verify your API token is valid and hasn't expired
Check that the endpoint URL is correct: https://api.operata.io/v1/mcp
Ensure your network allows HTTPS connections to api.operata.io
Verify your token has appropriate permissions

Tools Not Available in AI Client

Problem: The AI client doesn't show or use Operata tools.

Solutions:

Restart your AI client after updating the configuration
Verify the MCP configuration file syntax is correct (valid JSON)
Check the AI client logs for MCP-related errors

Authentication Errors

Problem: Receiving 401 Unauthorized or 403 Forbidden errors.

Solutions:

Regenerate your API token and update the configuration
Verify the token is correctly formatted in the Bearer authorization header
Check that your API token hasn't been revoked
Ensure the token has permissions for the operations you're attempting

Query Returns Unexpected Results

Problem: Data queries return empty results or incorrect data.

Solutions:

Verify your time ranges and filters in the query
Check that your API token is scoped to the correct Operata group
Ensure data exists for the query parameters specified
Try simplifying your query to isolate the issue

Support and Feedback

As this is an Alpha release, we value your feedback to help improve the Operata MCP Server.

For support:

Documentation: Review the Operata API Documentation
Email: Contact your Customer Success Manager

To provide feedback:

Share your use cases and feature requests with your CSM; or
Report bugs or issues via email

What's Next

We're actively developing additional features for the Operata MCP Server:

OAuth Integration: Full OAuth 2.0 support for ChatGPT and other clients
Additional Tools: More specialized tools for specific use cases
Enhanced Query Language: More powerful query syntax with filtering and aggregation
Resources: Direct access to Operata resources via MCP resource primitives
Prompts: Pre-built MCP prompts for common workflows

Stay tuned for updates as we move from Alpha to Beta and General Availability.

Ready to get started? Create your API token and configure your AI client to start querying Operata data.