Model Context Protocol (MCP)

One Connection, Complete Access: Cekura’s MCP server provides both documentation search and API operations in a single endpoint. Ask questions about Cekura, search integration guides, create agents, run tests, and analyze results—all through natural language with your AI assistant.

Prerequisites

Before setting up MCP, ensure you have:

Access to Cekura Dashboard
A valid Cekura API key
Node.js 20.18.1 or higher installed (for Claude Desktop, Cursor, and VS Code)
- Check your version: node --version
- Download from: nodejs.org

Setup

1. Get Your Cekura API Key

Navigate to API Settings

Create API Key

Click Create New Key and copy the generated API key

Store Securely

Save your API key in a secure location. You’ll need it for MCP configuration.

2. Configure MCP Server

Add the Cekura MCP server to your AI assistant:

Claude Code
Claude Desktop
Cursor
VS Code

Run the following command to add Cekura MCP server:

claude mcp add --transport http cekura --scope user https://api.cekura.ai/mcp --header "X-CEKURA-API-KEY:YOUR_API_KEY_HERE"

Verify the server is configured:

claude mcp list

Replace YOUR_API_KEY_HERE with your actual Cekura API key from the dashboard.

Open Claude Desktop
Go to Settings → Developer → Edit Config
Add the following configuration:

{
  "mcpServers": {
    "cekura": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.cekura.ai/mcp",
        "--header",
        "X-CEKURA-API-KEY:${CEKURA_API_KEY}"
      ],
      "env": {
        "CEKURA_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Replace YOUR_API_KEY_HERE with your actual Cekura API key from the dashboard.

Open Cursor
Press Cmd/Ctrl + Shift + P and search for “MCP: Edit Config”
Add the following configuration:

{
  "mcpServers": {
    "cekura": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.cekura.ai/mcp",
        "--header",
        "X-CEKURA-API-KEY:${CEKURA_API_KEY}"
      ],
      "env": {
        "CEKURA_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Replace YOUR_API_KEY_HERE with your actual Cekura API key from the dashboard.

Create or edit .vscode/mcp.json in your project
Add the following configuration:

{
  "mcpServers": {
    "cekura": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.cekura.ai/mcp",
        "--header",
        "X-CEKURA-API-KEY:${CEKURA_API_KEY}"
      ],
      "env": {
        "CEKURA_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Replace YOUR_API_KEY_HERE with your actual Cekura API key from the dashboard.

3. Verify Connection

Restart your AI assistant and verify the connection:

Ask your AI: "List my Cekura agents"

If configured correctly, your assistant will be able to interact with Cekura’s API.

How MCP Works

When you connect to Cekura’s MCP server, you get instant access to both documentation and APIs:

Unified Access

One connection provides 84+ tools: documentation search plus all documented API operations for testing, observability, and automation.

Documentation Search (No API Key Required)

Search across Cekura’s knowledge base for integration guides, API schemas, and feature documentation. Your AI assistant can answer questions without manual searches.

API Operations (API Key Required)

Create agents, run tests, analyze results, and manage your Cekura workspace directly through natural language commands.

Smart Tool Selection

Your AI assistant automatically chooses the right tools based on your requests—whether you’re asking questions or taking actions.

Secure Authentication

Your API key is automatically included in API requests via the X-CEKURA-API-KEY header. Documentation search requires no authentication.

Maximize Your Benefits

Get the most out of Cekura’s MCP integration:

1. Start with Learning, Then Execute

Learning Phase:

“How do I integrate with Retell?”
“What’s the schema for creating an agent?”
“Show me examples of custom metrics”

Execution Phase:

“Create an agent named ‘Support Bot’ for Retell”
“Run all evaluators for agent ID 123”
“Show me test results from the last 24 hours”

2. Scaffold Complete Integrations

Use comprehensive prompts to generate implementation plans:

"Create a comprehensive plan to integrate Cekura observability
with our Retell voice agent. Include API setup, metric definitions,
and webhook configuration."

Your AI will search documentation, understand patterns, and generate step-by-step implementation guides.

3. Iterate Quickly with Context

Your AI maintains context across questions and actions:

“What metrics are available?” → searches docs
“Create those metrics for my agent” → uses API
“Now generate 10 test scenarios” → uses API
“Run them” → uses API

4. Explore Without Leaving Your Editor

No need to switch between docs, dashboard, and code:

Ask about features while coding
Create test resources on the fly
Debug issues by checking API responses
Understand error messages in context

5. Combine Documentation with API Data

“Show me how to use custom metrics, then list my existing metrics”Your AI will:

Search docs to explain custom metrics
Call the API to show your actual metrics
Provide contextualized guidance based on your setup

The MCP server URL should be treated as a credential. Keep it secure and do not share it publicly.

Be mindful of context window limits. Large responses from Cekura APIs (like detailed transcripts) may consume significant context space.

Request Headers

Cekura’s MCP server uses the following headers for authentication and identification:

Header	Value	Description
`X-CEKURA-API-KEY`	Your API key	Required for authentication
`User-Agent`	`MCP-Client`	Identifies requests from MCP
`Content-Type`	`application/json`	Request payload format

All API requests through MCP require a valid API key in the X-CEKURA-API-KEY header.

Tool Configuration

Each Cekura API endpoint is exposed as an MCP tool with the following structure:

Required Fields

name: The tool identifier (e.g., list-agents, create-metric)
description: What the tool does
inputSchema: JSON schema defining required parameters

Optional Fields

examples: Example usage patterns
deprecated: Whether the endpoint is deprecated

Example Configuration

Cekura automatically configures all endpoints. Here’s what a typical tool looks like:

{
  "name": "list-agents",
  "description": "List all AI voice agents in your organization",
  "inputSchema": {
    "type": "object",
    "properties": {
      "page": {
        "type": "integer",
        "description": "Page number for pagination"
      },
      "limit": {
        "type": "integer",
        "description": "Number of results per page"
      }
    }
  }
}

Example Usage

Common workflows combining documentation search and API operations:

Learning Then Executing

User: "How do I integrate with Retell?"

AI: [Uses SearchCekura]
"Here's how to integrate with Retell:
1. Add your Retell API key in Settings
2. Create an agent and select 'Retell' as provider
3. Enter your Retell Assistant ID
[Provides detailed guide with links]"

User: "Create a Retell agent named 'Support Bot' with assistant ID abc123"

AI: [Uses create-agent API]
"I've created your Retell agent 'Support Bot' with ID 456.
Ready to configure test scenarios?"

Scaffolding Integrations

User: "Create a comprehensive plan to integrate Cekura observability"

AI: [Uses SearchCekura multiple times]
"Here's your integration plan:

1. Setup (5 min)
   - Get API key from Settings
   - Add webhook URL to your provider

2. Agent Configuration (10 min)
   - Create agent via POST /test_framework/v1/aiagents/
   - Required fields: name, contact_number, agent_type

3. Define Metrics (15 min)
   - Use SearchCekura for metric examples
   - POST /test_framework/v1/metrics/ to create

[Complete step-by-step plan with code examples]"

Combined Search and Action

User: "Show me my agents and explain how to create metrics for them"

AI: [Uses list-agents API + SearchCekura]
"Your agents:
1. Support Bot (ID: 123)
2. Sales Agent (ID: 456)

To create metrics for these agents:
- Custom metrics evaluate specific behaviors
- Use LLM-based or rule-based evaluation
[Provides examples and documentation links]

Would you like me to create specific metrics now?"

Best Practices

1. System Prompts with MCP References

Add a system prompt mentioning available tools:

You have access to Cekura tools that allow you to manage voice agents,
create test scenarios, and analyze call quality.

2. Secure Your API Keys

Never commit API keys to version control
Use environment variables for API keys
Rotate keys regularly
Create separate keys for different environments

3. Handle Rate Limits

Cekura enforces rate limits based on your plan:

Free: 1,000 requests/day
Pro: 10,000 requests/day
Enterprise: Custom limits

4. Monitor Usage

Check your MCP usage in the Cekura dashboard:

Navigate to Settings → API Usage
Monitor request counts and error rates
Set up alerts for unusual activity

5. Start with Read Operations

Begin by using read-only operations (GET endpoints) before using write operations (POST/PATCH/DELETE).

6. Test in Development First

Always test MCP configuration with a development API key before using production credentials.

Available Tools

Cekura’s MCP server provides 84+ tools across four main categories:

Documentation Search

No API key required

Search integration guides
Find API schemas and examples
Understand features and workflows
Get implementation patterns

Testing

Requires API key

Create and manage agents
Run test scenarios and evaluators
Define custom metrics
View and analyze test results

Observability

Requires API key

List and search call logs
Send calls for evaluation
Analyze call performance
Export call data

Automation

Requires API key

Create scheduled jobs
Manage cronjobs
Automate recurring tests
Configure alerts

For detailed information on each endpoint, see the API Reference.

Example MCP Providers

Make.com

Make.com provides MCP servers for workflow automation. Server URL Format:

https://hook.make.com/YOUR_WEBHOOK_ID

Zapier

Zapier offers MCP integration through webhooks. Server URL Format:

https://hooks.zapier.com/hooks/catch/YOUR_HOOK_ID/

Custom Servers

You can also run your own MCP server. See Building Custom MCP Servers for details.

Troubleshooting

API Key Authentication Failed

Error: 401 UnauthorizedSolutions:

Verify your API key is correct
Check the header name is X-CEKURA-API-KEY (case-sensitive)
Ensure the API key hasn’t expired
Generate a new API key from the dashboard

Tools Not Showing Up

Issue: AI assistant doesn’t see Cekura toolsSolutions:

Restart your AI assistant after configuration
Verify the MCP server URL is correct: https://api.cekura.ai/mcp
Check your configuration file syntax is valid JSON
Look for error messages in the assistant’s logs

Node.js Version Error (Windows)

Error: Unsupported engine or ReferenceError: File is not definedCause: Multiple Node.js versions installed, wrong version being usedSolution:

Check all Node.js installations:
```
where node
```

Find your Node v20+ installation:

node -e "console.log(process.execPath)"

Use the absolute path in your config:

{
  "mcpServers": {
    "cekura": {
      "command": "C:\\Full\\Path\\To\\node.exe",
      "args": [
        "C:\\Full\\Path\\To\\npx-cli.js",
        "-y",
        "mcp-remote",
        "https://api.cekura.ai/mcp",
        "--header",
        "X-CEKURA-API-KEY:${CEKURA_API_KEY}"
      ],
      "env": {
        "CEKURA_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Or uninstall older Node.js versions

Rate Limit Exceeded

Error: 429 Too Many RequestsSolutions:

Check your current usage in the dashboard
Upgrade your plan for higher limits
Implement request throttling in your workflows
Contact support for temporary limit increases

References

API Reference

Complete API documentation

Authentication

API key setup and management

Dashboard

Manage your API keys

Support

Get help with MCP setup

MCP

​Prerequisites

​Setup

​1. Get Your Cekura API Key

​2. Configure MCP Server

​3. Verify Connection

​How MCP Works

​Maximize Your Benefits

​Request Headers

​Tool Configuration

​Required Fields

​Optional Fields

​Example Configuration

​Example Usage

​Learning Then Executing

​Scaffolding Integrations

​Combined Search and Action

​Best Practices

​Available Tools

Documentation Search

Testing

Observability

Automation

​Example MCP Providers

​Make.com

​Zapier

​Custom Servers

​Troubleshooting

​References

API Reference

Authentication

Dashboard

Support

Prerequisites

Setup

1. Get Your Cekura API Key

2. Configure MCP Server

3. Verify Connection

How MCP Works

Maximize Your Benefits

Request Headers

Tool Configuration

Required Fields

Optional Fields

Example Configuration

Example Usage

Learning Then Executing

Scaffolding Integrations

Combined Search and Action

Best Practices

Available Tools

Example MCP Providers

Make.com

Zapier

Custom Servers

Troubleshooting

References