Oktivo MCP Server

A Model Context Protocol (MCP) server that enables LLMs to interact with Oktivo's voice AI platform. Create agents, trigger outbound calls, and manage call lifecycle — all through natural language.

Features

| Tool | Description | |------|-------------| | create_agent | Create a new AI voice agent with custom prompt, voice, and behavior | | update_agent | Modify an existing agent's configuration | | list_agents | List all agents in your account | | trigger_call | Trigger an outbound AI voice call to a phone number | | get_call_status | Check the status of a triggered call | | cancel_call | Cancel a pending/in-progress call |

Prerequisites

• Node.js 18+
• An Oktivo account
• An API token (generate from Settings → API Tokens in the dashboard)

Installation

npm install @oktivo/mcp-server

Or clone and build locally:

git clone <repo-url>
cd oktivo_mcp
npm install
npm run build

Configuration

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | OKTIVO_API_TOKEN | ✅ | — | Your Oktivo API token (okt_...) | | OKTIVO_BASE_URL | ❌ | https://client-backend.oktivo.com | API base URL |

Usage with LLM Clients

Option 1: npx (Recommended for Production)

After publishing to npm, users run:

{
  "mcpServers": {
    "oktivo": {
      "command": "npx",
      "args": ["-y", "@oktivo/mcp-server"],
      "env": {
        "OKTIVO_API_TOKEN": "okt_your_token_here"
      }
    }
  }
}

Option 2: Global Install

npm install -g @oktivo/mcp-server

Then configure:

{
  "mcpServers": {
    "oktivo": {
      "command": "oktivo-mcp",
      "env": {
        "OKTIVO_API_TOKEN": "okt_your_token_here"
      }
    }
  }
}

Option 3: Local Path (Development)

{
  "mcpServers": {
    "oktivo": {
      "command": "node",
      "args": ["E:/Oktivo/Oktivo/oktivo_mcp/dist/index.js"],
      "env": {
        "OKTIVO_API_TOKEN": "okt_your_token_here",
        "OKTIVO_BASE_URL": "http://localhost:3000"
      }
    }
  }
}

Client-Specific Configs

Claude Desktop — %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

Cursor — .cursor/mcp.json in your project or ~/.cursor/mcp.json globally

Kiro — .kiro/settings/mcp.json in your workspace or ~/.kiro/settings/mcp.json globally

Windsurf — .windsurf/mcp.json

Local Development

# Create .env file
echo "OKTIVO_API_TOKEN=okt_your_token" > .env
echo "OKTIVO_BASE_URL=http://localhost:3000" >> .env

# Run in dev mode (reads .env automatically)
npm run dev

Deployment

Option A: npm Registry (Recommended)

The simplest deployment — publish to npm and users install via npx:

# Login to npm
npm login

# Publish (scoped package)
npm publish --access public

Users then use:

{ "command": "npx", "args": ["-y", "@oktivo/mcp-server"] }

Option B: AWS Lambda + Streamable HTTP Transport

For server-side deployment where you don't want users running a local process:

1. Build the project: npm run build
2. Package dist/ and node_modules/ into a Lambda deployment zip
3. Set environment variables in Lambda config:
   • OKTIVO_API_TOKEN — service-level token (or pass per-user via headers)
   • OKTIVO_BASE_URL — https://client-backend.oktivo.com
4. Expose via API Gateway with the MCP Streamable HTTP transport

Note: For Lambda deployment you'd swap the stdio transport for the Streamable HTTP transport. The tool logic stays identical — only the transport layer changes.

Option C: Cloudflare Workers

Cloudflare Workers support MCP via the workers-mcp package or the Streamable HTTP transport:

1. Create a Cloudflare Worker project:

   npx wrangler init oktivo-mcp-worker

2. Set secrets:

   npx wrangler secret put OKTIVO_API_TOKEN

3. The worker would use Streamable HTTP transport instead of stdio:

   // worker entry — adapts the MCP server for Cloudflare
   import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
   import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

4. Deploy:

   npx wrangler deploy

Key difference: Cloudflare/AWS deployments use HTTP transport instead of stdio. The business logic (tools, client, config) remains unchanged — you only replace the transport initialization in index.ts.

Option D: Docker (Self-hosted)

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY dist/ ./dist/
ENTRYPOINT ["node", "dist/index.js"]

docker build -t oktivo-mcp .
docker run -e OKTIVO_API_TOKEN=okt_xxx oktivo-mcp

Architecture

src/
├── index.ts          # MCP server entry (stdio transport)
├── config.ts         # Environment variable resolution
├── client.ts         # HTTP client for Oktivo API
└── tools/
    ├── index.ts          # Tool registry
    ├── trigger-call.ts   # Trigger outbound call
    ├── get-call-status.ts # Get call status
    ├── cancel-call.ts    # Cancel call
    ├── create-agent.ts   # Create agent
    ├── update-agent.ts   # Update agent
    └── list-agents.ts    # List agents

Adding New Tools

1. Create a new file in src/tools/ (copy any existing tool as template)
2. Export from src/tools/index.ts
3. Register in src/index.ts
4. Build: npm run build

API Endpoints Used

| Endpoint | Method | Auth | Description | |----------|--------|------|-------------| | /api/v1/crm/calls | POST | API Token | Trigger outbound call | | /api/v1/crm/calls/:contactUID | GET | API Token | Get call status | | /api/v1/crm/calls/:contactUID | DELETE | API Token | Cancel call | | /api/v1/crm/agents | GET | API Token | List agents | | /create-agent | POST | JWT/Token | Create agent | | /update-agent/:agentId | PUT | JWT/Token | Update agent |

Rate Limits

| Endpoint | Limit | |----------|-------| | Trigger call | 60 requests/minute | | All other endpoints | 120 requests/minute |

License

MIT