Model Context Protocol (MCP)

Cekura provides an MCP server that exposes selected API endpoints for Observability, Testing, and Scheduling, allowing AI assistants like Claude Desktop, Cursor, and VS Code to interact with your agents, metrics, and test results.

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 Desktop
Cursor
VS Code

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

{
  "mcpServers": {
    "cekura": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://docs.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 add an MCP server to your AI assistant, here’s what happens:

Multiple Sessions Created

Cekura creates a unique MCP session for each conversation. The MCP tool itself is not meant to be invoked by the model directly.

Tools Become Available

All Cekura API endpoints become available as tools that your AI assistant can use automatically when needed.

Model Selects Tools

Based on your conversation, the AI assistant determines which Cekura tools to use (e.g., list agents, create metrics, get test results).

Authentication Handled

Your API key is automatically included in each request via the X-CEKURA-API-KEY header.

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

Here are common workflows using MCP with Cekura:

Listing Agents

User: "Show me all my Cekura agents"

AI: [Uses list-agents tool]
"You have 3 agents:
1. Customer Support Bot (active)
2. Sales Agent (active)
3. Test Agent (inactive)"

Creating Metrics

User: "Create a metric to check if the agent greeted the customer"

AI: [Uses create-metric tool]
"I've created a new metric called 'Greeting Quality' that evaluates
whether the agent properly greets customers at the start of calls."

Checking Test Results

User: "What are my latest test results?"

AI: [Uses list-results tool]
"Your most recent test run completed 2 hours ago with:
- 8/10 scenarios passed
- Average score: 87%
- 2 failures in error handling scenarios"

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 exposes core API endpoints as MCP tools across three main categories:

Observability

Monitor and analyze your calls

List and search call logs
Get call details
Send and evaluate calls
Export call data

Testing

Manage agents, tests, and metrics

Create and run test scenarios
Manage agents and evaluators
Define custom metrics
View test results

Schedules

Automate recurring tasks

Create scheduled jobs
Manage cronjobs
Update schedules

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://docs.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://docs.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

​Request Headers

​Tool Configuration

​Required Fields

​Optional Fields

​Example Configuration

​Example Usage

​Listing Agents

​Creating Metrics

​Checking Test Results

​Best Practices

​Available Tools

Observability

Testing

Schedules

​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

Request Headers

Tool Configuration

Required Fields

Optional Fields

Example Configuration

Example Usage

Listing Agents

Creating Metrics

Checking Test Results

Best Practices

Available Tools

Example MCP Providers

Make.com

Zapier

Custom Servers

Troubleshooting

References