> ## Documentation Index > Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt > Use this file to discover all available pages before exploring further. # MCP Quickstart > Connect your AI IDE to KaireonAI in 5 minutes ## Prerequisites * A KaireonAI instance (or the [playground](https://playground.kaireonai.com)) * 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](#hosted-mcp-endpoint-no-local-process) below — no local install required. ```bash theme={null} 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. ```bash theme={null} claude mcp add kaireonai -- npm --prefix /path/to/kaireonai/platform run mcp ``` Set environment variables in your Claude settings (`.claude/settings.json`): ```json theme={null} { "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`: ```json theme={null} { "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`: ```json theme={null} { "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: ```bash theme={null} 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](/api-reference/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](/api-reference/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. ```bash theme={null} 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](/integrations/mcp) for complete parameter documentation. ## Next Steps See all 162 tools with parameter documentation. Learn common AI-assisted workflows. Use the built-in AI assistant in the KaireonAI UI. Learn about the V2 pipeline architecture.