Skip to main content

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:
  1. Documentation MCP — Lets any AI client search your KaireonAI docs for answers, powered by Mintlify.
  2. 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

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.

Rate Limits

ScopeLimit
Per user (IP)5,000 requests/hour
Per documentation site1,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

VariableDescription
KAIREON_API_URLBase URL of your KaireonAI instance (e.g. http://localhost:3000)
KAIREON_API_KEYAPI key for authentication

Quick Setup

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

MCP Resources

The server also exposes one MCP resource:
ResourceURIDescription
platform-overviewkaireonai://overviewReturns counts of schemas, decision flows, and models

Tool Reference

All 110 tools organized by category. Parameters marked with ? are optional.

Data — Read (5 tools)

ToolDescriptionParameters
listSchemasList all data schemas with field names and types
getSchemaFieldsGet a single schema with its fields by IDschemaId: string
listPipelinesList all data pipelines with names and statuses
listConnectorsList all data connectors with types and statuses
listTransformTypesReturn the list of 14 supported pipeline transform types

Data — Write (5 tools)

ToolDescriptionParameters
createSchemaCreate a new data schema (creates a real PostgreSQL table)name: string, displayName: string, entityType?: string, description?: string
addSchemaFieldAdd 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
createConnectorCreate a data connector (18 types supported)name: string, type: string, description?: string, authMethod?: string
createPipelineCreate a data pipeline with connector and target schemaname: string, connectorId: string, schemaId: string, description?: string
addPipelineNodeAdd a node to a pipeline (source, transform, filter, target)pipelineId: string, nodeType: string, transformType?: string, label?: string

Data — Utility (1 tool)

ToolDescriptionParameters
testConnectorTest connectivity for an existing data connectorconnectorId: string

Studio — Read (4 tools)

ToolDescriptionParameters
listDecisionFlowsList all decision flows with names, statuses, and scoring methods
listOffersList all offers with names, statuses, and categories
listChannelsList all delivery channels with types and modes
listContactPoliciesList all contact policies (frequency caps, cooldowns, etc.)

Studio — Write (11 tools)

ToolDescriptionParameters
createOfferCreate a new offer/actionname: string, key: string, categoryId?: string, priority?: number, dailyBudget?: number, status?: string
createDecisionFlowCreate a new decision flowkey: string, name: string, description?: string, status?: string
createChannelCreate a delivery channelname: string, channelType?: string (email, sms, push, in_app, web, api), deliveryMode?: string (api, file, manual), description?: string, status?: string
createTreatmentCreate a creative content variant for an offer on a channelname: string, offerId: string, channelId: string, templateType?: string, content?: object, status?: string
createCategoryCreate an offer category (business issue grouping)name: string, description?: string, color?: string, status?: string
createSubCategoryCreate a sub-category under a parent categorycategoryId: string, name: string, description?: string, status?: string
createGuardrailCreate a guardrail rule to enforce business constraintskey: string, name: string, description?: string, severity?: string (hard, soft), status?: string
createContactPolicyCreate a contact policy (frequency cap, cooldown, etc.)name: string, ruleType: string, description?: string, scope?: string, config?: object, priority?: number
createTriggerCreate an event-driven trigger rulename: string, eventType: string, actionType: string, description?: string, priority?: number, cooldownMs?: number
createOutcomeTypeCreate an outcome type for tracking responseskey: string, name: string, classification?: string, category?: string, description?: string
createQualificationRuleDraft a qualification rule from natural-language (returns preview)description: string, scope: string, scopeId?: string

Studio — Draft Rules (1 tool)

ToolDescriptionParameters
createContactPolicyRuleDraft a contact policy rule from natural-language (returns preview)description: string

Studio — Mutations (7 tools)

ToolDescriptionParameters
updateOfferUpdate an existing offer by keyofferKey: string, name?: string, priority?: number, dailyBudget?: number, status?: string, schedulingStart?: string, schedulingEnd?: string
updateDecisionFlowUpdate an existing decision flow by keyflowKey: string, name?: string, description?: string, status?: string
updateChannelUpdate an existing channel by keychannelKey: string, name?: string, channelType?: string, deliveryMode?: string, status?: string
updateContactPolicyUpdate an existing contact policy by keypolicyKey: string, name?: string, priority?: number, status?: string, ruleType?: string, scope?: string, config?: object
updateQualificationRuleUpdate an existing qualification rule by keyruleKey: string, name?: string, status?: string, scope?: string, conditions?: object
deleteEntityDelete an entity by type and key/identityType: string (offer, decisionFlow, channel, contactPolicy, qualificationRule, experiment, guardrail, trigger), entityKey: string
publishDecisionFlowPublish a decision flow for production decisioningflowKey: string

Qualification Rules — Read (1 tool)

ToolDescriptionParameters
listQualificationRulesList all qualification rules with conditions and assigned offers

Algorithm — Read (2 tools)

ToolDescriptionParameters
listModelsList all algorithm models with types and statuses
listExperimentsList all A/B experiments with statuses and traffic splits

Algorithm — Write (2 tools)

ToolDescriptionParameters
trainModelTrigger training for an algorithm modelmodelId: string
createExperimentCreate a new A/B experimentkey: string, name: string, description?: string, championModelId?: string, status?: string

Model Management (4 tools)

ToolDescriptionParameters
getModelDetailsGet full details of a model including predictors, config, and metricsmodelId: string
addPredictorAdd a predictor property to a modelmodelId: string, field: string, schemaKey: string
removePredictorRemove a predictor property from a model by field namemodelId: string, field: string
updateModelConfigUpdate a model’s target field or learning configmodelId: string, targetField?: string, targetSchemaKey?: string

Behavioral Metrics — Read (2 tools)

ToolDescriptionParameters
listBehavioralMetricsList all behavioral metric definitions
previewMetricValuesPreview top 20 computed values for a metricmetricId: string, customerId?: string

Behavioral Metrics — Write (3 tools)

ToolDescriptionParameters
createBehavioralMetricCreate a behavioral metric definitionname: string, aggregateFunction: string (count, sum, avg, min, max, ratio), sourceField: string, windowDays?: number, groupByDimensions?: string[], filterConditions?: object, computeMode?: string, description?: string
computeMetricNowTrigger immediate batch computation for a metricmetricId: string
createMetricRuleCreate a contact policy or qualification rule using a metrictype: 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)

ToolDescriptionParameters
queryMetricQuery an aggregated metric (e.g. conversion_rate, decision_count)metric: string, period?: string (1d, 7d, 30d, 90d)
listAlertsList active alerts and anomalies

Decisioning (2 tools)

ToolDescriptionParameters
recommendRun the decision engine for a customer (core NBA API)customerId: string, channel?: string, limit?: number, decisionFlowKey?: string, attributes?: object
recordOutcomeRecord a customer response/outcome for attribution and feedbackcustomerId: string, offerId: string, creativeId: string, outcome: string, channelId?: string, conversionValue?: number, metadata?: object

Decision Traces (2 tools)

ToolDescriptionParameters
listDecisionTracesList recent decision traces (forensic audit trail)customerId?: string, offerId?: string, decisionFlowId?: string, limit?: number
getDecisionTraceGet full details of a single decision tracerecommendationId: string

Customer Data (2 tools)

ToolDescriptionParameters
queryCustomerDataQuery customer data from a schema table with filtersschemaId: string, filters?: object, limit?: number, offset?: number
getCustomerProfileGet a customer’s 360 profile across all schemascustomerId: string

Journeys (3 tools)

ToolDescriptionParameters
listJourneysList all customer journeys with names and statuses
getJourneyGet a journey by ID with full configurationjourneyId: string
createJourneyCreate a new customer journeyname: string, description?: string, triggerType?: string, status?: string

Interactions & History (1 tool)

ToolDescriptionParameters
listInteractionsList interaction history with filterscustomerId?: string, offerId?: string, channel?: string, since?: string (ISO date), limit?: number

Segments (2 tools)

ToolDescriptionParameters
listSegmentsList all customer segments with member counts
getSegmentMembersGet members of a specific segmentsegmentId: string, limit?: number, offset?: number

Approval Workflow (3 tools)

ToolDescriptionParameters
listApprovalRequestsList approval requests (optionally filter by status)status?: string (pending, approved, rejected)
approveRequestApprove a pending approval requestrequestId: string, comment?: string
rejectRequestReject a pending approval requestrequestId: string, reason: string

Tenant Settings (2 tools)

ToolDescriptionParameters
getTenantSettingsGet current tenant settings and feature toggles
updateTenantSettingsUpdate tenant settings (feature toggles, trace config, etc.)settings: object

Pipeline Runs (2 tools)

ToolDescriptionParameters
triggerPipelineRunTrigger an execution run for a pipelinepipelineId: string
getPipelineRunStatusGet the status of a specific pipeline runpipelineId: string, runId: string

Audit Logs (1 tool)

ToolDescriptionParameters
listAuditLogsList audit log entries with filtersaction?: string, entityType?: string, userId?: string, since?: string (ISO 8601), limit?: number

Docs Search (1 tool)

ToolDescriptionParameters
searchDocsSearch KaireonAI platform documentationquery: string

AI Content Generation (2 tools)

ToolDescriptionParameters
generateCreativeCopyAI-generate marketing copy for an offerofferName: string, channelType: string, tone?: string, maxLength?: number
generateSubjectLinesAI-generate email subject line variants for A/B testingofferName: string, count?: number

CMS Content Management (7 tools)

ToolDescriptionParameters
listContentItemsList content items with optional filtersstatus?: string, channelType?: string, isTemplate?: boolean, sourceType?: string
getContentItemGet a content item by ID with version historyid: string
createContentItemCreate a new content item (starts as draft)name: string, channelType: string, content?: object, isTemplate?: boolean
updateContentItemUpdate a content item’s fieldsid: string, name?: string, content?: object, blocks?: array, personalization?: array
publishContentItemPublish a content item (must be in approved status)id: string
generateContentVariantsAI-generate content variants for A/B testingofferName: string, channelType: string, variantCount?: number, tone?: string
listContentSourcesList connected external CMS sources

CMS Sync (1 tool)

ToolDescriptionParameters
syncContentSourceTrigger a manual sync from an external CMS sourceid: string

Intelligence & Analytics (12 tools)

These tools provide deep analysis, simulation, and explainability for your decisioning platform.
ToolDescriptionParameters
explainDecisionExplain 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
traceCustomerJourneyTrace a customer’s activity timeline: interactions, journey enrollments, experiment assignmentscustomerId: string, limit?: number
compareOfferEligibilityCompare 2-5 offers side-by-side for a customer: qualification pass/fail, policy blocks, scorescustomerId: string, offerIds: string[] (2-5 items)
listCustomerSuppressionsList all active contact policy suppressions for a customercustomerId: string
analyzeQualificationFunnelAnalyze the decision funnel to find where candidates are filtered outdecisionFlowKey?: string
analyzeContactPolicySuppressionAnalyze suppression rates by rule type and channelchannel?: string, period?: string (day, week, month)
analyzePolicyConflictsDetect conflicts between offers, rules, policies, and experiments
analyzeOfferPerformanceAnalyze offer impressions, conversions, revenue, and trendsperiod?: string (day, week, month), limit?: number
simulateRuleChangeSimulate the impact of a qualification rule or policy changeruleId: string, proposedChange: object (field: string, oldValue: any, newValue: any)
simulateFrequencyCapChangeSimulate the impact of changing a frequency capchannel: string, currentCap: number, newCap: number, period: string (day, week, month)
analyzeModelHealthAnalyze ML model health: AUC, precision, recall, trends, data freshnessmodelId: string
runHealthCheckComprehensive tenant health check: models, policies, budgets, experiments

Model Intelligence (3 tools)

ToolDescriptionParameters
explainModelScoringExplain how a model scores a customer: raw score, percentile, top contributing featuresmodelId: string, customerId: string
suggestModelImprovementsSuggest improvements: missing predictors, model type, training frequencymodelId: string
detectModelDriftDetect model drift: scoring distribution vs training metrics, calibration checkmodelId: string

V2 Pipeline (9 tools)

The V2 composable pipeline introduces a 3-phase, 13-node-type architecture for decision flows.
ToolDescriptionParameters
listV2NodeTypesList all 13 V2 node types organized by phase
listScoringMethodsList scoring methods: priority_weighted, propensity (ML), formula (weighted composite)
listRankMethodsList the 4 ranking methods: topN, diversity, round_robin, explore_exploit
listGroupAllocationStrategiesList placement allocation strategies: optimal (Hungarian), greedy
getDecisionFlowConfigGet the full V2 pipeline config for a decision flowflowKey: string
addV2PipelineNodeAdd a node to a V2 pipeline at the correct phase positionflowKey: string, nodeType: string (one of 13 types), nodeConfig: object
removeV2PipelineNodeRemove a node from a V2 pipeline by node IDflowKey: string, nodeId: string
updateV2PipelineNodeConfigUpdate configuration of a specific V2 pipeline nodeflowKey: string, nodeId: string, nodeConfig: object
createV2DecisionFlowCreate a new V2 decision flow with a default 4-node pipelinekey: 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 TypeDescription
inventoryLoad candidate offers (all, by category, or manual selection)
match_creativesMatch offers to creatives/placements
enrichLoad customer data from schema tables with caching
qualifyApply qualification rules with AND/OR logic trees
contact_policyApply contact policies (frequency caps, cooldowns)
filterCustom filter conditions (13 operators: eq, neq, gt, gte, lt, lte, in, not_in, contains, starts_with, regex, is_null, is_not_null)
call_flowSub-invoke another decision flow (max depth 2, circular reference guard)

Phase 2 — Score & Rank

Score candidates and select the best ones.
Node TypeDescription
scoreScore using priority_weighted, propensity (ML), or formula. Supports per-channel overrides and champion/challenger.
rankRank using topN, diversity, round_robin, or explore_exploit methods
groupAllocate candidates to named placements using optimal (Hungarian) or greedy strategy

Phase 3 — Output

Compute personalized values and format the response.
Node TypeDescription
computeEvaluate computed fields with formula overrides and extras
set_propertiesAttach key-value properties or formula-derived values to candidates
responseConfigure response format (standard or grouped) and debug trace toggle

Scoring Methods

MethodML RequiredDescription
priority_weightedNoScore based on offer priority (0-100)
propensityYesScore using an ML model’s propensity prediction
formulaNoWeighted 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

MethodDescriptionKey Config
topNSort by score descending, return top NmaxCandidates
diversityRound-robin by category with backfillmaxCandidates, maxPerCategory
round_robinStrict equal representation per categorymaxCandidates, maxPerCategory
explore_exploitEpsilon-greedy: exploit top scores, explore the restmaxCandidates, explorationRate (0.0-1.0)

Supported Connector Types

The createConnector tool supports 18 connector types:
TypeAuth Methods
aws_s3iam_role, access_key
gcsservice_account_json
azure_blobconnection_string, access_key
sftpusername_password
kafkausername_password, none
snowflakeusername_password, oauth2
databricksaccess_key, oauth2
bigqueryservice_account_json
redshiftusername_password
postgresqlconnection_string, username_password
mysqlconnection_string, username_password
mongodbconnection_string
salesforceoauth2
hubspotapi_key, oauth2
segmentapi_key
brazeapi_key
rest_apiapi_key, oauth2, none
webhooknone, api_key

Contact Policy Rule Types

The createContactPolicy tool supports these rule types:
Rule TypeDescription
frequency_capLimit number of contacts per time period
cooldownEnforce minimum time between contacts
budget_exhaustedBlock when budget is depleted
outcome_basedRules triggered by customer outcomes
segment_exclusionExclude specific customer segments
time_windowRestrict to specific time windows
mutual_exclusionPrevent conflicting offers from being shown together
cross_channel_capCap across multiple channels
allow_overrideOverride 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

CategoryCount
Data (Read + Write + Utility)11
Studio (Read + Write + Draft Rules + Mutations)23
Qualification Rules Read1
Algorithms & Models8
Behavioral Metrics5
Dashboard & Reporting2
Decisioning2
Decision Traces2
Customer Data2
Journeys3
Interactions1
Segments2
Approvals3
Tenant Settings2
Pipeline Runs2
Audit Logs1
Docs Search1
AI Content Generation2
CMS Content Management + Sync8
Intelligence & Analytics15
V2 Pipeline9
Total110