MCP Quickstart

Prerequisites

A KaireonAI instance (or the playground)
An API key (from Settings > API Explorer)
Your tenant ID
Node.js 22+ installed

Step 1: Clone and Install

Running the MCP server from source applies to Dedicated private cloud and Enterprise on-prem deployments, where you have repository access under your commercial license. On Playground or Cloud, skip straight to the hosted MCP endpoint below — no local install required.

git clone https://github.com/kaireonai/platform.git
cd platform
npm install

Step 2: Configure Your IDE

All four IDE configurations below invoke the same MCP server entry point. The recommended invocation is npm run mcp from inside the cloned platform/ directory — it resolves the entry script for you so the configuration does not need to hard-code a source-tree path.

Claude Code
Cursor
VS Code
npm Script

claude mcp add kaireonai -- npm --prefix /path/to/kaireonai/platform run mcp

Set environment variables in your Claude settings (.claude/settings.json):

{
  "mcpServers": {
    "kaireonai": {
      "command": "npm",
      "args": ["--prefix", "/path/to/kaireonai/platform", "run", "mcp"],
      "env": {
        "KAIREON_API_URL": "https://playground.kaireonai.com",
        "KAIREON_API_KEY": "your-api-key",
        "KAIREON_TENANT_ID": "your-tenant-id"
      }
    }
  }
}

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "kaireonai": {
      "command": "npm",
      "args": ["--prefix", "/path/to/kaireonai/platform", "run", "mcp"],
      "env": {
        "KAIREON_API_URL": "https://playground.kaireonai.com",
        "KAIREON_API_KEY": "your-api-key",
        "KAIREON_TENANT_ID": "your-tenant-id"
      }
    }
  }
}

Create .vscode/mcp.json:

{
  "servers": {
    "kaireonai": {
      "type": "stdio",
      "command": "npm",
      "args": ["--prefix", "/path/to/kaireonai/platform", "run", "mcp"],
      "env": {
        "KAIREON_API_URL": "https://playground.kaireonai.com",
        "KAIREON_API_KEY": "your-api-key",
        "KAIREON_TENANT_ID": "your-tenant-id"
      }
    }
  }
}

You can also start the server directly from a shell:

cd platform
KAIREON_API_URL=https://playground.kaireonai.com \
KAIREON_API_KEY=your-api-key \
KAIREON_TENANT_ID=your-tenant-id \
npm run mcp

Replace /path/to/kaireonai/platform with the absolute path to your cloned repository’s platform directory.

Step 3: Your First Queries

Try these natural language commands in your AI IDE:

Explore your setup

List all my data schemas

Show me the active Decision Flows

What offers do I have configured?

Create entities

Create a new offer called "Summer Savings" in the cross-sell category with priority 75

Create a V2 decision flow called "cross-sell-v2" with diversity ranking and 5 max candidates

Add an enrich node to the cross-sell-v2 flow that loads customer data from the customers schema

Analyze and simulate

Run a health check on my tenant

Explain why customer C-1234 didn't receive the premium card offer

Simulate what happens if I lower the email frequency cap to 2 per week

V2 Pipeline operations

What scoring methods are available?

List the ranking algorithms I can use

Add a filter node to my flow that only keeps offers where priority > 50

Update the score node in my flow to use formula scoring with 40% propensity, 30% value, 20% context, 10% lever

Step 4: Build a Complete Setup

Here’s a full workflow you can give to your AI IDE:

Help me set up a complete telecom cross-sell decisioning flow:
1. Create a "telecom_customers" schema with fields: customer_id, tenure, monthly_spend, plan_type
2. Create two offers: "5G Upgrade" (priority 80) and "Family Plan" (priority 60)
3. Create an email channel
4. Create a V2 decision flow with:
   - Enrich from telecom_customers
   - Qualify: only customers with tenure > 12 months
   - Score with formula method (50% propensity, 30% value, 20% context)
   - Rank using diversity to mix offer categories
   - Return top 3 offers
5. Run a health check when done

Troubleshooting

”KAIREON_API_KEY environment variable is required”

Make sure the environment variables are set in your IDE’s MCP configuration, not just your shell. Each IDE reads env vars from its own config file.

”API error: 401”

Your API key is invalid or expired. Generate a new one from Settings > API Explorer in the KaireonAI UI.

”API error: 403”

Your API key doesn’t have permission for that operation. Check the role assigned to the key in Settings. If the error body says the key “is scoped to the data plane (recommend / respond)”, the key was minted without the control-plane scope — management endpoints and the hosted MCP endpoint require a key minted with scopes: ["control-plane"] (admin only; see API Keys).

”Flow is not V2”

The Decision Flow you’re trying to modify uses the legacy (V1) config format. Use createV2DecisionFlow to create a new V2 flow, or manually set draftConfig.version = 2 in the UI canvas editor.

Server won’t start

Ensure you have Node.js 22+ and have run npm install in the platform directory. The MCP server requires the @modelcontextprotocol/sdk and zod packages.

Hosted MCP endpoint (no local process)

If you’d rather not run a local server, KaireonAI also exposes a hosted MCP endpoint at POST /api/v1/mcp — the same tool surface over stateless JSON-RPC 2.0 (no SSE). It supports initialize, ping, tools/list, and tools/call, authenticated with the same X-API-Key + X-Tenant-Id headers (the key needs the editor or admin role). The authenticated tenant is forced into every call, and mutating operations are routed through the governed approval flow rather than writing directly.

The hosted MCP endpoint is a control-plane surface: the API key must be minted with the control-plane scope (admin only; see API Keys). A default data-plane-only key gets 403 on /api/v1/mcp. Keep the key internal — it is a management credential; never embed it in client apps.

curl -s https://playground.kaireonai.com/api/v1/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -H "X-Tenant-Id: your-tenant-id" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Available Tools

The MCP server exposes 162 tools (plus 10 governed playbooks) organized by module:

Category	Count	Examples
Studio (offers, flows, channels, creatives, policies, metrics, decisioning)	67	`listOffers`, `createOffer`, `createDecisionFlow`, `recommend`, `recordOutcome`
Data (schemas, connectors, pipelines, segments)	24	`listSchemas`, `createSchema`, `listConnectors`, `listTransformTypes`
Algorithms & Models	26	`listModels`, `createModel`, `listExperiments`, `getModelDetails`
AI & Content Intelligence	26	`searchDocs`, `generateCreativeCopy`, `generateSubjectLines`
Flow / Pipeline (IR)	11	`createFlowPipeline`, `runFlowPipeline`, `listFlowRuns`
Operations & Governance	8	`queryMetric`, `listAlerts`, `listApprovalRequests`, `approveRequest`

See the full MCP Server Reference for complete parameter documentation.

Next Steps

MCP Server Reference

See all 162 tools with parameter documentation.

AI Workflows

Learn common AI-assisted workflows.

AI Assistant

Use the built-in AI assistant in the KaireonAI UI.

Composable Pipeline

Learn about the V2 pipeline architecture.

Get Started

Tutorials

Use Cases

Decisioning

Studio

Data Pipelines

AI & ML

Operations & Reporting

Governance & Security

Integrations

Reference

Prerequisites

Step 1: Clone and Install

Step 2: Configure Your IDE

Step 3: Your First Queries

Explore your setup

Create entities

Analyze and simulate

V2 Pipeline operations

Step 4: Build a Complete Setup

Troubleshooting

”KAIREON_API_KEY environment variable is required”

”API error: 401”

”API error: 403”

”Flow is not V2”

Server won’t start

Hosted MCP endpoint (no local process)

Available Tools

Next Steps

MCP Server Reference

AI Workflows

AI Assistant

Composable Pipeline

​Prerequisites

​Step 1: Clone and Install

​Step 2: Configure Your IDE

​Step 3: Your First Queries

​Explore your setup

​Create entities

​Analyze and simulate

​V2 Pipeline operations

​Step 4: Build a Complete Setup

​Troubleshooting

​”KAIREON_API_KEY environment variable is required”

​”API error: 401”

​”API error: 403”

​”Flow is not V2”

​Server won’t start

​Hosted MCP endpoint (no local process)

​Available Tools

​Next Steps

MCP Server Reference

AI Workflows

AI Assistant

Composable Pipeline

Prerequisites

Step 1: Clone and Install

Step 2: Configure Your IDE

Step 3: Your First Queries

Explore your setup

Create entities

Analyze and simulate

V2 Pipeline operations

Step 4: Build a Complete Setup

Troubleshooting

”KAIREON_API_KEY environment variable is required”

”API error: 401”

”API error: 403”

”Flow is not V2”

Server won’t start

Hosted MCP endpoint (no local process)

Available Tools

Next Steps