Overview
KaireonAI exposes 110 tools via the Model Context Protocol (MCP), allowing AI agents in Claude Code, Cursor, VS Code Copilot, and other MCP-compatible IDEs to fully manage your decisioning platform — including the V2 composable pipeline with 14 node types, 4 ranking algorithms, channel overrides, and sub-flow invocation.
KaireonAI offers two MCP integrations:
- Documentation MCP — Lets any AI client search your KaireonAI docs for answers, powered by Mintlify.
- Platform MCP — Exposes 110 platform tools so AI assistants can manage your KaireonAI instance directly.
Four tool categories:
- CRUD Tools — Create, read, update, delete every entity (schemas, offers, decision flows, pipelines, etc.)
- Decisioning Tools — Run recommendations, record outcomes, query traces
- Intelligence Tools — Analyze performance, explain decisions, simulate changes, detect drift
- Agent Playbooks — Higher-level composable workflows (
playbook_*) that chain 5-10 primitive tools into a single named operation. See Agent Playbooks for the full list.
MCP is an open protocol that standardizes how AI applications connect to external data sources and tools. Any MCP-compatible client — Claude Code, Cursor, VS Code, ChatGPT, and others — can connect to these servers.
Documentation MCP (Mintlify)
Mintlify automatically generates an MCP server from your published documentation. When an AI client connects, it can search your docs directly instead of relying on generic web searches — meaning answers are always accurate and up to date.
Your documentation MCP server is hosted at:
https://docs.kaireonai.com/mcp
Connecting to AI Clients
Claude Code
Cursor
VS Code
Claude Web
Run this command in your terminal:claude mcp add --transport http kaireonai-docs https://docs.kaireonai.com/mcp
Once added, Claude Code can search KaireonAI docs when answering your questions. Add to your mcp.json configuration:{
"mcpServers": {
"kaireonai-docs": {
"url": "https://docs.kaireonai.com/mcp"
}
}
}
Create or edit .vscode/mcp.json in your project:{
"servers": {
"kaireonai-docs": {
"type": "http",
"url": "https://docs.kaireonai.com/mcp"
}
}
}
- Go to Settings > Connectors in Claude.
- Click Add Connector.
- Enter
kaireonai-docs as the name and https://docs.kaireonai.com/mcp as the URL.
Rate Limits
| Scope | Limit |
|---|
| Per user (IP) | 5,000 requests/hour |
| Per documentation site | 1,000 requests/hour |
The Documentation MCP is available on all Mintlify plans, including free. No additional setup is needed — Mintlify generates and hosts the server automatically when your docs are deployed.
Environment Variables
| Variable | Description |
|---|
KAIREON_API_URL | Base URL of your KaireonAI instance (e.g. http://localhost:3000) |
KAIREON_API_KEY | API key for authentication |
Quick Setup
Claude Code
Cursor / VS Code
npm Script
claude mcp add kaireonai -- npx -y tsx src/mcp/server.ts
Set environment variables in your Claude Code config or shell profile:export KAIREON_API_URL=http://localhost:3000
export KAIREON_API_KEY=your-api-key
Add to your MCP configuration file:{
"mcpServers": {
"kaireonai": {
"command": "npx",
"args": ["-y", "tsx", "src/mcp/server.ts"],
"env": {
"KAIREON_API_URL": "http://localhost:3000",
"KAIREON_API_KEY": "your-api-key"
}
}
}
}
From the platform/ directory:
MCP Resources
The server also exposes one MCP resource:
| Resource | URI | Description |
|---|
platform-overview | kaireonai://overview | Returns counts of schemas, decision flows, and models |
All 110 tools organized by category. Parameters marked with ? are optional.
| Tool | Description | Parameters |
|---|
listSchemas | List all data schemas with field names and types | — |
getSchemaFields | Get a single schema with its fields by ID | schemaId: string |
listPipelines | List all data pipelines with names and statuses | — |
listConnectors | List all data connectors with types and statuses | — |
listTransformTypes | Return the list of 14 supported pipeline transform types | — |
| Tool | Description | Parameters |
|---|
createSchema | Create a new data schema (creates a real PostgreSQL table) | name: string, displayName: string, entityType?: string, description?: string |
addSchemaField | Add a new field (column) to a schema (runs ALTER TABLE) | schemaId: string, fieldName: string, dataType: string (text, integer, decimal, boolean, timestamp, date, json, uuid), nullable: boolean |
createConnector | Create a data connector (18 types supported) | name: string, type: string, description?: string, authMethod?: string |
createPipeline | Create a data pipeline with connector and target schema | name: string, connectorId: string, schemaId: string, description?: string |
addPipelineNode | Add a node to a pipeline (source, transform, filter, target) | pipelineId: string, nodeType: string, transformType?: string, label?: string |
| Tool | Description | Parameters |
|---|
testConnector | Test connectivity for an existing data connector | connectorId: string |
| Tool | Description | Parameters |
|---|
listDecisionFlows | List all decision flows with names, statuses, and scoring methods | — |
listOffers | List all offers with names, statuses, and categories | — |
listChannels | List all delivery channels with types and modes | — |
listContactPolicies | List all contact policies (frequency caps, cooldowns, etc.) | — |
| Tool | Description | Parameters |
|---|
createOffer | Create a new offer/action | name: string, key: string, categoryId?: string, priority?: number, dailyBudget?: number, status?: string |
createDecisionFlow | Create a new decision flow | key: string, name: string, description?: string, status?: string |
createChannel | Create a delivery channel | name: string, channelType?: string (email, sms, push, in_app, web, api), deliveryMode?: string (api, file, manual), description?: string, status?: string |
createTreatment | Create a creative content variant for an offer on a channel | name: string, offerId: string, channelId: string, templateType?: string, content?: object, status?: string |
createCategory | Create an offer category (business issue grouping) | name: string, description?: string, color?: string, status?: string |
createSubCategory | Create a sub-category under a parent category | categoryId: string, name: string, description?: string, status?: string |
createGuardrail | Create a guardrail rule to enforce business constraints | key: string, name: string, description?: string, severity?: string (hard, soft), status?: string |
createContactPolicy | Create a contact policy (frequency cap, cooldown, etc.) | name: string, ruleType: string, description?: string, scope?: string, config?: object, priority?: number |
createTrigger | Create an event-driven trigger rule | name: string, eventType: string, actionType: string, description?: string, priority?: number, cooldownMs?: number |
createOutcomeType | Create an outcome type for tracking responses | key: string, name: string, classification?: string, category?: string, description?: string |
createQualificationRule | Draft a qualification rule from natural-language (returns preview) | description: string, scope: string, scopeId?: string |
| Tool | Description | Parameters |
|---|
createContactPolicyRule | Draft a contact policy rule from natural-language (returns preview) | description: string |
| Tool | Description | Parameters |
|---|
updateOffer | Update an existing offer by key | offerKey: string, name?: string, priority?: number, dailyBudget?: number, status?: string, schedulingStart?: string, schedulingEnd?: string |
updateDecisionFlow | Update an existing decision flow by key | flowKey: string, name?: string, description?: string, status?: string |
updateChannel | Update an existing channel by key | channelKey: string, name?: string, channelType?: string, deliveryMode?: string, status?: string |
updateContactPolicy | Update an existing contact policy by key | policyKey: string, name?: string, priority?: number, status?: string, ruleType?: string, scope?: string, config?: object |
updateQualificationRule | Update an existing qualification rule by key | ruleKey: string, name?: string, status?: string, scope?: string, conditions?: object |
deleteEntity | Delete an entity by type and key/id | entityType: string (offer, decisionFlow, channel, contactPolicy, qualificationRule, experiment, guardrail, trigger), entityKey: string |
publishDecisionFlow | Publish a decision flow for production decisioning | flowKey: string |
| Tool | Description | Parameters |
|---|
listQualificationRules | List all qualification rules with conditions and assigned offers | — |
| Tool | Description | Parameters |
|---|
listModels | List all algorithm models with types and statuses | — |
listExperiments | List all A/B experiments with statuses and traffic splits | — |
| Tool | Description | Parameters |
|---|
trainModel | Trigger training for an algorithm model | modelId: string |
createExperiment | Create a new A/B experiment | key: string, name: string, description?: string, championModelId?: string, status?: string |
| Tool | Description | Parameters |
|---|
getModelDetails | Get full details of a model including predictors, config, and metrics | modelId: string |
addPredictor | Add a predictor property to a model | modelId: string, field: string, schemaKey: string |
removePredictor | Remove a predictor property from a model by field name | modelId: string, field: string |
updateModelConfig | Update a model’s target field or learning config | modelId: string, targetField?: string, targetSchemaKey?: string |
| Tool | Description | Parameters |
|---|
listBehavioralMetrics | List all behavioral metric definitions | — |
previewMetricValues | Preview top 20 computed values for a metric | metricId: string, customerId?: string |
| Tool | Description | Parameters |
|---|
createBehavioralMetric | Create a behavioral metric definition | name: string, aggregateFunction: string (count, sum, avg, min, max, ratio), sourceField: string, windowDays?: number, groupByDimensions?: string[], filterConditions?: object, computeMode?: string, description?: string |
computeMetricNow | Trigger immediate batch computation for a metric | metricId: string |
createMetricRule | Create a contact policy or qualification rule using a metric | type: string (contactPolicy or qualification), name: string, metricId: string, operator: string (gt, gte, lt, lte, eq), threshold: number, dimensionMapping?: object, scope?: string, scopeEntityId?: string |
| Tool | Description | Parameters |
|---|
queryMetric | Query an aggregated metric (e.g. conversion_rate, decision_count) | metric: string, period?: string (1d, 7d, 30d, 90d) |
listAlerts | List active alerts and anomalies | — |
| Tool | Description | Parameters |
|---|
recommend | Run the decision engine for a customer (core NBA API) | customerId: string, channel?: string, limit?: number, decisionFlowKey?: string, attributes?: object |
recordOutcome | Record a customer response/outcome for attribution and feedback | customerId: string, offerId: string, creativeId: string, outcome: string, channelId?: string, conversionValue?: number, metadata?: object |
| Tool | Description | Parameters |
|---|
listDecisionTraces | List recent decision traces (forensic audit trail) | customerId?: string, offerId?: string, decisionFlowId?: string, limit?: number |
getDecisionTrace | Get full details of a single decision trace | recommendationId: string |
| Tool | Description | Parameters |
|---|
queryCustomerData | Query customer data from a schema table with filters | schemaId: string, filters?: object, limit?: number, offset?: number |
getCustomerProfile | Get a customer’s 360 profile across all schemas | customerId: string |
| Tool | Description | Parameters |
|---|
listJourneys | List all customer journeys with names and statuses | — |
getJourney | Get a journey by ID with full configuration | journeyId: string |
createJourney | Create a new customer journey | name: string, description?: string, triggerType?: string, status?: string |
Interactions & History (1 tool)
| Tool | Description | Parameters |
|---|
listInteractions | List interaction history with filters | customerId?: string, offerId?: string, channel?: string, since?: string (ISO date), limit?: number |
| Tool | Description | Parameters |
|---|
listSegments | List all customer segments with member counts | — |
getSegmentMembers | Get members of a specific segment | segmentId: string, limit?: number, offset?: number |
| Tool | Description | Parameters |
|---|
listApprovalRequests | List approval requests (optionally filter by status) | status?: string (pending, approved, rejected) |
approveRequest | Approve a pending approval request | requestId: string, comment?: string |
rejectRequest | Reject a pending approval request | requestId: string, reason: string |
| Tool | Description | Parameters |
|---|
getTenantSettings | Get current tenant settings and feature toggles | — |
updateTenantSettings | Update tenant settings (feature toggles, trace config, etc.) | settings: object |
| Tool | Description | Parameters |
|---|
triggerPipelineRun | Trigger an execution run for a pipeline | pipelineId: string |
getPipelineRunStatus | Get the status of a specific pipeline run | pipelineId: string, runId: string |
| Tool | Description | Parameters |
|---|
listAuditLogs | List audit log entries with filters | action?: string, entityType?: string, userId?: string, since?: string (ISO 8601), limit?: number |
| Tool | Description | Parameters |
|---|
searchDocs | Search KaireonAI platform documentation | query: string |
AI Content Generation (2 tools)
| Tool | Description | Parameters |
|---|
generateCreativeCopy | AI-generate marketing copy for an offer | offerName: string, channelType: string, tone?: string, maxLength?: number |
generateSubjectLines | AI-generate email subject line variants for A/B testing | offerName: string, count?: number |
CMS Content Management (7 tools)
| Tool | Description | Parameters |
|---|
listContentItems | List content items with optional filters | status?: string, channelType?: string, isTemplate?: boolean, sourceType?: string |
getContentItem | Get a content item by ID with version history | id: string |
createContentItem | Create a new content item (starts as draft) | name: string, channelType: string, content?: object, isTemplate?: boolean |
updateContentItem | Update a content item’s fields | id: string, name?: string, content?: object, blocks?: array, personalization?: array |
publishContentItem | Publish a content item (must be in approved status) | id: string |
generateContentVariants | AI-generate content variants for A/B testing | offerName: string, channelType: string, variantCount?: number, tone?: string |
listContentSources | List connected external CMS sources | — |
| Tool | Description | Parameters |
|---|
syncContentSource | Trigger a manual sync from an external CMS source | id: string |
These tools provide deep analysis, simulation, and explainability for your decisioning platform.
| Tool | Description | Parameters |
|---|
explainDecision | Explain why a customer received (or didn’t receive) an offer. Shows the full funnel: inventory, qualification, contact policy, scoring, ranking. | customerId: string, offerId?: string, decisionFlowKey?: string |
traceCustomerJourney | Trace a customer’s activity timeline: interactions, journey enrollments, experiment assignments | customerId: string, limit?: number |
compareOfferEligibility | Compare 2-5 offers side-by-side for a customer: qualification pass/fail, policy blocks, scores | customerId: string, offerIds: string[] (2-5 items) |
listCustomerSuppressions | List all active contact policy suppressions for a customer | customerId: string |
analyzeQualificationFunnel | Analyze the decision funnel to find where candidates are filtered out | decisionFlowKey?: string |
analyzeContactPolicySuppression | Analyze suppression rates by rule type and channel | channel?: string, period?: string (day, week, month) |
analyzePolicyConflicts | Detect conflicts between offers, rules, policies, and experiments | — |
analyzeOfferPerformance | Analyze offer impressions, conversions, revenue, and trends | period?: string (day, week, month), limit?: number |
simulateRuleChange | Simulate the impact of a qualification rule or policy change | ruleId: string, proposedChange: object (field: string, oldValue: any, newValue: any) |
simulateFrequencyCapChange | Simulate the impact of changing a frequency cap | channel: string, currentCap: number, newCap: number, period: string (day, week, month) |
analyzeModelHealth | Analyze ML model health: AUC, precision, recall, trends, data freshness | modelId: string |
runHealthCheck | Comprehensive tenant health check: models, policies, budgets, experiments | — |
| Tool | Description | Parameters |
|---|
explainModelScoring | Explain how a model scores a customer: raw score, percentile, top contributing features | modelId: string, customerId: string |
suggestModelImprovements | Suggest improvements: missing predictors, model type, training frequency | modelId: string |
detectModelDrift | Detect model drift: scoring distribution vs training metrics, calibration check | modelId: string |
The V2 composable pipeline introduces a 3-phase, 13-node-type architecture for decision flows.
| Tool | Description | Parameters |
|---|
listV2NodeTypes | List all 13 V2 node types organized by phase | — |
listScoringMethods | List scoring methods: priority_weighted, propensity (ML), formula (weighted composite) | — |
listRankMethods | List the 4 ranking methods: topN, diversity, round_robin, explore_exploit | — |
listGroupAllocationStrategies | List placement allocation strategies: optimal (Hungarian), greedy | — |
getDecisionFlowConfig | Get the full V2 pipeline config for a decision flow | flowKey: string |
addV2PipelineNode | Add a node to a V2 pipeline at the correct phase position | flowKey: string, nodeType: string (one of 13 types), nodeConfig: object |
removeV2PipelineNode | Remove a node from a V2 pipeline by node ID | flowKey: string, nodeId: string |
updateV2PipelineNodeConfig | Update configuration of a specific V2 pipeline node | flowKey: string, nodeId: string, nodeConfig: object |
createV2DecisionFlow | Create a new V2 decision flow with a default 4-node pipeline | key: string, name: string, description?: string, scoringMethod?: string, rankMethod?: string, maxCandidates?: number |
V2 Pipeline Node Types
The V2 pipeline organizes nodes into three sequential phases:
Phase 1 — Narrow
Filter and enrich the candidate pool.
| Node Type | Description |
|---|
inventory | Load candidate offers (all, by category, or manual selection) |
match_creatives | Match offers to creatives/placements |
enrich | Load customer data from schema tables with caching |
qualify | Apply qualification rules with AND/OR logic trees |
contact_policy | Apply contact policies (frequency caps, cooldowns) |
filter | Custom filter conditions (13 operators: eq, neq, gt, gte, lt, lte, in, not_in, contains, starts_with, regex, is_null, is_not_null) |
call_flow | Sub-invoke another decision flow (max depth 2, circular reference guard) |
Phase 2 — Score & Rank
Score candidates and select the best ones.
| Node Type | Description |
|---|
score | Score using priority_weighted, propensity (ML), or formula. Supports per-channel overrides and champion/challenger. |
rank | Rank using topN, diversity, round_robin, or explore_exploit methods |
group | Allocate candidates to named placements using optimal (Hungarian) or greedy strategy |
Phase 3 — Output
Compute personalized values and format the response.
| Node Type | Description |
|---|
compute | Evaluate computed fields with formula overrides and extras |
set_properties | Attach key-value properties or formula-derived values to candidates |
response | Configure response format (standard or grouped) and debug trace toggle |
Scoring Methods
| Method | ML Required | Description |
|---|
priority_weighted | No | Score based on offer priority (0-100) |
propensity | Yes | Score using an ML model’s propensity prediction |
formula | No | Weighted composite: propensityWeight * modelScore + contextWeight * (priority/100) + valueWeight * (creativeWeight/100) + leverWeight * fitMultiplier. Weights must sum to 1.0. |
Channel overrides allow per-channel scoring configuration. Each override specifies a channelId and an alternative method/model/formula. Falls back to the default if no override matches.
Champion/Challenger enables A/B testing of scoring models. The champion gets majority traffic; challengers get the rest based on weight split.
Ranking Methods
| Method | Description | Key Config |
|---|
topN | Sort by score descending, return top N | maxCandidates |
diversity | Round-robin by category with backfill | maxCandidates, maxPerCategory |
round_robin | Strict equal representation per category | maxCandidates, maxPerCategory |
explore_exploit | Epsilon-greedy: exploit top scores, explore the rest | maxCandidates, explorationRate (0.0-1.0) |
Supported Connector Types
The createConnector tool supports 18 connector types:
| Type | Auth Methods |
|---|
aws_s3 | iam_role, access_key |
gcs | service_account_json |
azure_blob | connection_string, access_key |
sftp | username_password |
kafka | username_password, none |
snowflake | username_password, oauth2 |
databricks | access_key, oauth2 |
bigquery | service_account_json |
redshift | username_password |
postgresql | connection_string, username_password |
mysql | connection_string, username_password |
mongodb | connection_string |
salesforce | oauth2 |
hubspot | api_key, oauth2 |
segment | api_key |
braze | api_key |
rest_api | api_key, oauth2, none |
webhook | none, api_key |
The createContactPolicy tool supports these rule types:
| Rule Type | Description |
|---|
frequency_cap | Limit number of contacts per time period |
cooldown | Enforce minimum time between contacts |
budget_exhausted | Block when budget is depleted |
outcome_based | Rules triggered by customer outcomes |
segment_exclusion | Exclude specific customer segments |
time_window | Restrict to specific time windows |
mutual_exclusion | Prevent conflicting offers from being shown together |
cross_channel_cap | Cap across multiple channels |
allow_override | Override other policies for priority offers |
Example Workflows
Create an Offer and Get Recommendations
1. createSchema → Create a "customers" schema
2. addSchemaField → Add fields (name, segment, tenure)
3. createCategory → Create "Retention" category
4. createOffer → Create "Loyalty Upgrade" offer
5. createChannel → Create "email" channel
6. createTreatment → Create email creative for the offer
7. createV2DecisionFlow → Create a V2 pipeline
8. recommend → Get recommendations for a customer
9. recordOutcome → Record the customer's response
1. analyzeOfferPerformance → See top/bottom performing offers
2. analyzeQualificationFunnel → Find where candidates are being filtered out
3. explainDecision → Understand why a specific customer got specific offers
4. simulateRuleChange → Test impact of loosening a qualification rule
5. runHealthCheck → Full platform health assessment
Build a V2 Pipeline from Scratch
1. createV2DecisionFlow → Start with default 4-node pipeline
2. addV2PipelineNode → Add "enrich" node to load customer data
3. addV2PipelineNode → Add "qualify" node with rules
4. addV2PipelineNode → Add "contact_policy" node
5. updateV2PipelineNodeConfig → Configure scoring method
6. updateV2PipelineNodeConfig → Set rank method to "diversity"
7. publishDecisionFlow → Make it live
| Category | Count |
|---|
| Data (Read + Write + Utility) | 11 |
| Studio (Read + Write + Draft Rules + Mutations) | 23 |
| Qualification Rules Read | 1 |
| Algorithms & Models | 8 |
| Behavioral Metrics | 5 |
| Dashboard & Reporting | 2 |
| Decisioning | 2 |
| Decision Traces | 2 |
| Customer Data | 2 |
| Journeys | 3 |
| Interactions | 1 |
| Segments | 2 |
| Approvals | 3 |
| Tenant Settings | 2 |
| Pipeline Runs | 2 |
| Audit Logs | 1 |
| Docs Search | 1 |
| AI Content Generation | 2 |
| CMS Content Management + Sync | 8 |
| Intelligence & Analytics | 15 |
| V2 Pipeline | 9 |
| Total | 110 |