MCP Integration

Connect KaireonAI to any AI IDE with 130 MCP tools

Overview

KaireonAI exposes 130 tools via the Model Context Protocol (MCP) — 120 primitive tools registered across src/mcp/tools/*.ts plus 10 composable Agent Playbooks registered from src/lib/mcp/playbooks/. Together they let AI agents in Claude Code, Cursor, VS Code Copilot, and other MCP-compatible IDEs 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:

1. Documentation MCP — Lets any AI client search your KaireonAI docs for answers, powered by Mintlify.
2. Platform MCP — Exposes 130 platform tools (120 primitives + 10 playbooks) 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

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.

Cursor

Add to your mcp.json configuration:

{
  "mcpServers": {
    "kaireonai-docs": {
      "url": "https://docs.kaireonai.com/mcp"
    }
  }
}

VS Code

Create or edit .vscode/mcp.json in your project:

{
  "servers": {
    "kaireonai-docs": {
      "type": "http",
      "url": "https://docs.kaireonai.com/mcp"
    }
  }
}

Claude Web

1. Go to Settings > Connectors in Claude.
2. Click Add Connector.
3. 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.

---

Platform MCP Setup

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
KAIREON_TENANT_ID	Tenant id (default default)
MCP_ALLOW_WRITES	Set to true to allow write tools (POST/PUT/DELETE/PATCH) in production. In NODE_ENV=production the server is read-only by default; with the override unset, every write tool is rejected before the underlying API call is issued.

Quick Setup

Claude Code

claude mcp add kaireonai -- npm --prefix platform run mcp

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

Cursor / VS Code

Add to your MCP configuration file:

{
  "mcpServers": {
    "kaireonai": {
      "command": "npm",
      "args": ["--prefix", "platform", "run", "mcp"],
      "env": {
        "KAIREON_API_URL": "http://localhost:3000",
        "KAIREON_API_KEY": "your-api-key"
      }
    }
  }
}

npm Script

From the platform/ directory:

npm run mcp

MCP Resources

The server also exposes one MCP resource:

Resource	URI	Description
platform-overview	kaireonai://overview	Returns counts of schemas, decision flows, and models

---

Tool Reference

All 120 primitive tools organized by category. The 10 playbook_* tools are documented separately at Agent Playbooks. Parameters marked with ? are optional.

Data — Read (5 tools)

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	—

Data — Write (5 tools)

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
createFlowPipeline	Create an IR-native pipeline with full Pipeline IR document	name: string, connectorId: string, schemaId: string, ir: object, description?: string
updateFlowPipeline	Save a new IR version against an existing pipeline (validated server-side via parsePipelineIR)	pipelineId: string, ir: object, comment?: string

Data — Utility (1 tool)

Tool	Description	Parameters
testConnector	Test connectivity for an existing data connector	connectorId: string

Studio — Read (4 tools)

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.)	—

Studio — Write

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

Studio — Draft Rules (1 tool)

Tool	Description	Parameters
createContactPolicyRule	Draft a contact policy rule from natural-language (returns preview)	description: string

Studio — Mutations (7 tools)

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

Qualification Rules — Read (1 tool)

Tool	Description	Parameters
listQualificationRules	List all qualification rules with conditions and assigned offers	—

Algorithm — Read (2 tools)

Tool	Description	Parameters
listModels	List all algorithm models with types and statuses	—
listExperiments	List all A/B experiments with statuses and traffic splits	—

Algorithm — Write (2 tools)

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

Model Management (4 tools)

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

Behavioral Metrics — Read (2 tools)

Tool	Description	Parameters
listBehavioralMetrics	List all behavioral metric definitions	—
previewMetricValues	Preview top 20 computed values for a metric	metricId: string, customerId?: string

Behavioral Metrics — Write (3 tools)

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

Dashboard & Reporting (2 tools)

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	—

Decisioning (2 tools)

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

Decision Traces (2 tools)

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

Customer Data (2 tools)

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

Journeys (3 tools)

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

Segments (2 tools)

Tool	Description	Parameters
listSegments	List all customer segments with member counts	—
getSegmentMembers	Get members of a specific segment	segmentId: string, limit?: number, offset?: number

Approval Workflow (3 tools)

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

Tenant Settings (2 tools)

Tool	Description	Parameters
getTenantSettings	Get current tenant settings and feature toggles	—
updateTenantSettings	Update tenant settings (feature toggles, trace config, etc.)	settings: object

Pipeline Runs (2 tools)

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

Audit Logs (1 tool)

Tool	Description	Parameters
listAuditLogs	List audit log entries with filters	action?: string, entityType?: string, userId?: string, since?: string (ISO 8601), limit?: number

Docs Search (1 tool)

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	—

CMS Sync (1 tool)

Tool	Description	Parameters
syncContentSource	Trigger a manual sync from an external CMS source	id: string

Intelligence & Analytics (12 tools)

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	—

Every invocation of these tools updates the kaireon_ai_intelligence_calls_total Counter and kaireon_ai_intelligence_duration_seconds Histogram. See Metrics Reference for alert guidance.

Model Intelligence (3 tools)

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

V2 Pipeline (9 tools)

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 Decision-Flow Transforms (5 tools)

Transforms attach to an enrich or compute node inside a V2 decision flow and run per-candidate at decision time — orthogonal to the Pipeline IR transforms used by the Flow data plane. The 11 in-memory transform types listed below operate on the in-flight candidate record and feed into the next node’s input. The five MCP tools below cover listing, adding, removing, and inspecting these per-node transforms.

Tool	Read/Write	Description	Parameters
listFlowTransformTypes	Read	List all 11 in-memory transform types with their config schemas (orthogonal to Flow IR transforms).	—
addEnrichTransform	Write	Append a transform to the enrich node of a V2 decision flow. Runs after customer data is loaded from schema tables. Returns 4xx if the flow is not V2 or no enrich node exists.	flowId: string, transform: { type, config }
addComputeTransform	Write	Append a transform to the compute node of a V2 decision flow. Runs after formula-based computed fields are evaluated.	flowId: string, transform: { type, config }
removeNodeTransform	Write	Remove a transform from an enrich or compute node by zero-based index.	flowId: string, nodeType: enrich | compute, index: number
listNodeTransforms	Read	Enumerate all transforms configured on an enrich or compute node, with their indices.	flowId: string, nodeType: enrich | compute

The 11 transform types (type field):

type	Config
rename_field	{ from, to }
cast_type	{ field, targetType: number | string | boolean }
expression	{ targetField, formula } — supports customer.*, attributes.*, arithmetic
map_values	{ field, mapping, defaultValue? }
hash	{ field, algorithm: sha256 | md5, targetField? }
mask_pii	{ field, maskType: first_n | last_n | all, chars? }
split_field	{ field, delimiter, targetFields }
merge_fields	{ fields, delimiter, targetField }
drop_field	{ field }
add_field	{ field, type, defaultValue }
filter_condition	{ formula } (boolean)

The three write tools (addEnrichTransform, addComputeTransform, removeNodeTransform) issue an HTTP PUT /api/v1/decision-flows to persist the change. In production they require MCP_ALLOW_WRITES=true; without the override the server rejects the call with MCP write operation blocked before any HTTP request leaves the process. The two read tools (listFlowTransformTypes, listNodeTransforms) execute in any mode.

---

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 (PRIE): propensityWeight * modelScore + relevanceWeight * (priority/100) + impactWeight * (creativeWeight/100) + emphasisWeight * 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 the following 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

---

Contact Policy Rule Types

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

Analyze Decision Performance

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

---

Tool Count Summary

Counted per source area to match the live registration count exposed by the running MCP server:

Source area	Count
AI tools	26
Algorithm tools	13
Data tools	16
Flow tools	11
Operations tools	8
Studio tools	46
Primitive tools subtotal	120
Agent Playbooks (playbook_*) — see Agent Playbooks	10
Total	130