MCP Integration - KaireonAI

Overview

KaireonAI exposes 172 tools via the Model Context Protocol (MCP) — 162 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 16 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 172 platform tools (162 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
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.

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. Must be a control-plane-scoped key — the MCP tools call management endpoints (schemas, decision flows, models, content, …), so a default data-plane-only key gets `403`. Mint with `scopes: ["control-plane"]` (admin only; see API Keys)
`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
Cursor / VS Code
npm Script

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

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"
      }
    }
  }
}

From the platform/ directory:

npm run mcp

Hosted Endpoint (no local process)

The same tool surface is also reachable over HTTP at POST /api/v1/mcp — a stateless JSON-RPC 2.0 endpoint (no SSE) so remote agents can call the tools without running the local stdio server. It implements initialize, ping, tools/list, and tools/call, authenticated with the standard X-API-Key + X-Tenant-Id headers (the key must have the editor or admin role). The authenticated tenant is forced into every call, and mutating playbook applies are routed through the governed approval flow instead of writing directly.

The hosted MCP endpoint is a control-plane surface — its tools can invoke management endpoints. 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. Treat it as a management credential — keep it internal and never embed it in client apps. The in-app AI assistant is unaffected (it uses a browser session, not an API key).

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"}'

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 162 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 19 supported pipeline transform op types (16 runtime-implemented; `summarize`, `vector_embed`, `geo_resolve` are schema-defined but passthrough at runtime)	—

Data — Write (12 tools)

Tool	Description	Parameters
`createSchema`	Create a new data schema (creates a real PostgreSQL table)	`name`: string, `displayName`: string, `entityType?`: `"customer" \| "account" \| "custom"` (default `"custom"`; the `customer` schema is the base `customer.*` in every decision), `description?`: string, `customPrimaryKey?`: `{ name, dataType }`, `fields?`: `Array<{name, dataType, isPrimaryKey?, isNullable?, isUnique?, length?, precision?, scale?, defaultValue?, ordinal?, description?}>` (use for composite PKs or initial multi-column schemas)
`deleteSchema`	Delete a schema, its field metadata, and the backing `ds_*` table (irreversible)	`schemaId`: string
`addSchemaField`	Add a new field (column) to a schema (runs ALTER TABLE). Duplicate names return 409 unless `upsert: true` is set.	`schemaId`: string, `name`: string, `dataType`: string (`varchar`, `text`, `integer`, `bigint`, `smallint`, `numeric`, `decimal`, `float`, `real`, `double`, `boolean`, `date`, `timestamp`, `timestamptz`, `json`, `uuid`), `isNullable?`: boolean, `isPrimaryKey?`: boolean, `isUnique?`: boolean, `isPredictor?`: boolean, `length?`: number, `precision?`: number, `scale?`: number, `defaultValue?`: string, `description?`: string, `displayName?`: string, `upsert?`: boolean
`updateSchemaField`	Alter an existing column — rename, change type/length/nullable/description. Runs `ALTER TABLE`. Cannot alter PK columns. Cast errors return 422.	`fieldId`: string, `newName?`: string, `dataType?`: string, `length?`: number, `precision?`: number, `scale?`: number, `isNullable?`: boolean, `displayName?`: string, `description?`: string
`removeSchemaField`	Drop a column from a schema (irreversible — data lost)	`fieldId`: string
`createConnector`	Create a data connector (18 types supported)	`name`: string, `type`: string, `description?`: string, `authMethod?`: string, `connectorConfig?`: object (connection params), `authConfig?`: object (credentials, encrypted at rest)
`updateConnector`	Update a connector’s name, description, config, or credentials. Omit `authConfig` to preserve existing credentials; sending an empty object overwrites them.	`connectorId`: string, `name?`: string, `description?`: string, `connectorConfig?`: object, `authMethod?`: string, `authConfig?`: object, `status?`: string
`deleteConnector`	Delete a connector (irreversible; pipelines referencing it will fail)	`connectorId`: string
`createPipeline`	Create a data pipeline with connector and target schema (legacy metadata-only)	`name`: string, `connectorId`: string, `schemaId`: string, `description?`: string
`createFlowPipeline`	Create an IR-native pipeline with full Pipeline IR document (auto-injects `irVersion: "1.0"`)	`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. Returns `{success, message, warning, latencyMs}` — note `warning` is transient and not persisted to `lastError`.	`connectorId`: string

Studio — Read (8 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.)	—
`listTreatments`	List all treatments (creatives — content variants tied to offers and channels). Closes BUG-MCP-STUDIO-018.	—
`listGuardrails`	List all guardrail rules (business-constraint filters that block/warn on candidates). Closes BUG-MCP-STUDIO-019.	—
`listTriggers`	List all event-driven trigger rules. Closes BUG-MCP-STUDIO-020.	—
`listOutcomeTypes`	List all outcome types (impression / response classifications — e.g. clicked, purchased, dismissed). Closes BUG-MCP-STUDIO-021.	—

Studio — Write

Tool	Description	Parameters
`createOffer`	Create a new offer/action (rich field surface — matches the `/api/v1/offers` POST body)	`name`: string, `categoryId?`: string, `subCategoryId?`: string, `category?`: string, `group?`: string, `productType?`: string, `priority?`: number, `businessValue?`: number, `margin?`: number, `revenueValue?`: number, `description?`: string, `shortDesc?`: string, `eligibility?`: object, `budget?`: object (`{ maxSpend, costPerAction, maxImpressions }`), `schedule?`: object (`{ startDate, endDate, daysOfWeek, timeWindows }`), `tags?`: string[], `metadata?`: object, `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`, `integration`), `couplingMode?`: string (`partial`, `atomic`), `providerConfig?`: object, `description?`: string, `status?`: string
`deleteChannel`	Soft-delete a channel by ID	`channelId`: string
`createTreatment`	Create a creative content variant for an offer on a channel. Closes BUG-MCP-STUDIO-022 — rich surface: placementId, personalization, constraints, abTestVariant, weight, metrics.	`name`: string, `offerId`: string, `channelId`: string, `placementId?`: string, `templateType?`: string, `content?`: object, `personalization?`: array, `constraints?`: object, `abTestVariant?`: string, `weight?`: number, `metrics?`: object, `status?`: string
`createCategory`	Create an offer category (top-level offer grouping)	`name`: string, `description?`: string, `icon?`: string, `color?`: string, `status?`: string, `ordinal?`: number, `customFields?`: array
`updateCategory`	Update an offer category (name, description, icon, color, status, ordinal, customFields)	`categoryId`: string, `name?`: string, `description?`: string, `icon?`: string, `color?`: string, `status?`: string, `ordinal?`: number, `customFields?`: array
`deleteCategory`	Soft-delete a category (sub-categories cascade, offers unlinked)	`categoryId`: string
`createSubCategory`	Create a sub-category under a parent category	`categoryId`: string, `name`: string, `description?`: string, `icon?`: string, `status?`: string, `ordinal?`: number, `customFields?`: array
`updateSubCategory`	Update an existing sub-category (name, description, icon, status, ordinal, customFields)	`subCategoryId`: string, `name?`: string, `description?`: string, `icon?`: string, `status?`: string, `ordinal?`: number, `customFields?`: array
`deleteSubCategory`	Soft-delete a sub-category (offers in it are unlinked)	`subCategoryId`: string
`createGuardrail`	Create a guardrail rule to enforce business constraints. Closes BUG-MCP-STUDIO-025 — `expressionAst` (the actual filter expression) is now exposable; previously it was hard-coded to `{}` so every MCP-created guardrail was a no-op.	`key`: string, `name`: string, `description?`: string, `severity?`: string (`hard`, `soft`), `expressionAst?`: object, `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. Closes BUG-MCP-STUDIO-027 — `condition` and `actionConfig` are now exposable; previously hard-coded to `{}` so triggers had no filter and no action payload.	`name`: string, `eventType`: string, `actionType`: string, `condition?`: object (`{ all?: rules[], any?: rules[] }`), `actionConfig?`: object, `description?`: string, `priority?`: number, `cooldownMs?`: number
`createOutcomeType`	Create an outcome type for tracking responses. Closes BUG-MCP-STUDIO-029 — `ordinal` and `status` are now exposable.	`key`: string, `name`: string, `classification?`: string, `category?`: string, `description?`: string, `ordinal?`: number, `status?`: string
`createQualificationRule`	Create a real decisioning gate (was preview-only — Closes BUG-MCP-STUDIO-036). Posts to `/api/v1/qualification-rules` with the discriminated union for ruleType.	`name`: string, `ruleType`: string (`segment_required` \| `attribute_condition` \| `propensity_threshold` \| `recency_check` \| `metric_condition`), `config`: object (shape depends on ruleType), `description?`: string, `scope?`: string, `scopeId?`: string, `scopes?`: array, `stage?`: string (`eligibility` default), `priority?`: number, `status?`: string
`draftQualificationRule`	Draft a decisioning gate from natural-language (returns preview only — was previously the `createQualificationRule` tool). Pair with `createQualificationRule` to actually save.	`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 (16 tools)

Update/delete tools accept the entity’s UUID or name as identifier — the API’s resolveEntityId helper resolves either. For entities that also carry a key field (decisionFlow, guardrail, outcomeType), the key works too.

Tool	Description	Parameters
`updateOffer`	Update an existing offer (action) by ID or name. Full update surface — pass `budget`/`schedule` as JSON blobs, not the legacy `dailyBudget`/`schedulingStart`/`schedulingEnd` (those were silently dropped before — fixed in BUG-MCP-STUDIO-010).	`offer`: string, plus any of: `name`, `categoryId`, `subCategoryId`, `category`, `group`, `productType`, `priority`, `businessValue`, `margin`, `revenueValue`, `description`, `shortDesc`, `eligibility`, `budget`, `schedule`, `tags`, `metadata`, `status`
`updateDecisionFlow`	Update an existing decision flow by key or UUID. Closes BUG-MCP-STUDIO-037 — previously sent `body.key` but `/api/v1/decision-flows` PUT requires `body.id` (UUID), so every update returned `400 "id is required"` even with a valid key. Now resolves key→id client-side. Full surface.	`flowKey`: string, plus any of: `name`, `description`, `status`, `autoAssembly`, `isProtected`, `couplingOverride`, `rankingProfileId`, `skipContactPolicy`, `draftConfig`
`updateChannel`	Update an existing channel by ID or name (BUG-MCP-STUDIO-011 — Channel has no `key`, the old `channelKey` lookup always 404’d)	`channel`: string, plus any of: `name`, `channelType`, `deliveryMode`, `impressionMode`, `couplingMode`, `providerConfig`, `fileConfig`, `description`, `status`
`updateContactPolicy`	Update an existing contact policy by ID or name (BUG-MCP-STUDIO-012)	`policy`: string, plus any of: `name`, `priority`, `status`, `ruleType`, `scope`, `config`
`updateQualificationRule`	Update an existing decisioning gate by ID or name (BUG-MCP-STUDIO-013)	`rule`: string, plus any of: `name`, `status`, `scope`, `conditions`
`updateTreatment`	Update an existing treatment (creative) by ID or name. Closes BUG-MCP-STUDIO-023.	`treatment`: string, plus any of: `name`, `offerId`, `channelId`, `placementId`, `templateType`, `content`, `personalization`, `constraints`, `abTestVariant`, `weight`, `metrics`, `status`
`updateGuardrail`	Update an existing guardrail rule by key. Closes BUG-MCP-STUDIO-026.	`key`: string, plus any of: `name`, `description`, `severity`, `expressionAst`, `status`
`updateTrigger`	Update an existing trigger rule by ID or name (resolved by the trigger route’s `resolvePathId`). Closes BUG-MCP-STUDIO-028. Also note: BUG-MCP-STUDIO-032 — the platform middleware previously bypassed all of `/api/v1/triggers/`, dropping admin role-injection for the CRUD route; that bypass is now narrowed to only the webhook endpoints.	`trigger`: string, plus any of: `name`, `description`, `eventType`, `actionType`, `condition`, `actionConfig`, `priority`, `cooldownMs`, `status`
`updateOutcomeType`	Update an existing outcome type by ID. Closes BUG-MCP-STUDIO-030.	`outcomeTypeId`: string, plus any of: `key`, `name`, `description`, `classification`, `category`, `ordinal`, `status`
`deleteOffer`	Soft-delete an offer by ID or name (BUG-MCP-STUDIO-014 — dedicated delete; the old generic `deleteEntity(offer, key)` did key-lookup against keyless Offer)	`offer`: string
`deleteContactPolicy`	Soft-delete a contact policy by ID or name (BUG-MCP-STUDIO-015)	`policy`: string
`deleteQualificationRule`	Soft-delete a decisioning gate by ID or name (BUG-MCP-STUDIO-016)	`rule`: string
`deleteTreatment`	Soft-delete a treatment (creative) by ID or name. Closes BUG-MCP-STUDIO-024 — deleteEntity didn’t cover creatives.	`treatment`: string
`deleteOutcomeType`	Soft-delete an outcome type by ID (system outcome types are protected at the API). Closes BUG-MCP-STUDIO-031.	`outcomeTypeId`: string
`deleteEntity`	Delete an entity by type and identifier (BUG-MCP-STUDIO-017 — now passes identifier straight to the API for UUID/key/name resolution; previously did broken key-lookup on keyless models). Supports: `offer`, `decisionFlow`, `channel`, `contactPolicy`, `qualificationRule`, `experiment`, `guardrail`, `trigger`.	`entityType`: string, `entityKey`: string (UUID or name; key for keyed entities)
`publishDecisionFlow`	Publish a decision flow for production decisioning. Closes BUG-MCP-STUDIO-038 — same key vs id mismatch as updateDecisionFlow. Now resolves key→id client-side and accepts optional publish notes.	`flowKey`: string, `notes?`: string

Decisioning Gates — Read (1 tool)

Tool	Description	Parameters
`listQualificationRules`	List all decisioning gates with conditions and assigned offers	—

Algorithm — Read (3 tools)

Tool	Description	Parameters
`listModels`	List all algorithm models with types and statuses	—
`listExperiments`	List all A/B experiments with statuses and traffic splits	—
`listModelTypes`	List the 9 supported algorithm-model types (scorecard, bayesian, logistic_regression, gradient_boosted, thompson_bandit, epsilon_greedy, neural_cf, online_learner, external_endpoint) with descriptions. Closes BUG-MCP-ALGO-001.	—

Algorithm — Write (6 tools)

Tool	Description	Parameters
`createModel`	Create a new algorithm model (any of 9 modelTypes). Closes BUG-MCP-ALGO-002 — no createModel tool existed; the entire model surface was unreachable from MCP.	`key`: string, `name`: string, `modelType`: string, `description?`: string, `status?`: string, `config?`: object, `targetField?`: string, `targetSchemaKey?`: string, `predictors?`: array, `learningConfig?`: object, `autoLearn?`: boolean, `learnMode?`: string (`none`/`incremental`/`scheduled`/`both`), `learnSchedule?`: string
`deleteModel`	Soft-delete a model by ID. Closes BUG-MCP-ALGO-003.	`modelId`: string
`trainModel`	Trigger training for an algorithm model	`modelId`: string
`createExperiment`	Create a new A/B experiment. Closes BUG-MCP-ALGO-005 — surface expanded from 5 → 11 fields (trafficSplit, autoPromote, promoteThreshold, promoteAfterDays, holdoutPercent, challengers).	`key`: string, `name`: string, `championModelId?`: string, `trafficSplit?`: object (`{ championPct: N }`), `challengers?`: array (`[{modelId, trafficPct}]`), `autoPromote?`: boolean, `promoteThreshold?`: number, `promoteAfterDays?`: number, `holdoutPercent?`: number, `description?`: string, `status?`: string
`updateExperiment`	Update an existing experiment by ID or name. Closes BUG-MCP-ALGO-006.	`experimentId`: string, plus any of: `name`, `description`, `status`, `championModelId`, `trafficSplit`, `challengers`, `autoPromote`, `promoteThreshold`, `promoteAfterDays`, `holdoutPercent`, `results`
`deleteExperiment`	Delete an experiment by ID or name. Closes BUG-MCP-ALGO-007.	`experimentId`: string

Model Management (6 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`	Narrow legacy wrapper — only `targetField`/`targetSchemaKey`. Prefer `updateModel` for the full surface.	`modelId`: string, `targetField?`: string, `targetSchemaKey?`: string
`updateModel`	Update an algorithm model — full 16-field surface (name, description, status, config, predictors, learningConfig, autoLearn, learnMode, learnSchedule, outcomeWeights, interactionFeatures, evolutionConfig, metrics, modelState, targetField, targetSchemaKey). Accepts UUID or name via resolvePathId. Closes BUG-MCP-ALGO-004.	`modelId`: string, plus any of the 16 fields above
`getExperimentResults`	Get computed experiment results: uplift, p-value, sample sizes, per-variant rates. Closes BUG-MCP-ALGO-008.	`experimentId`: string

Ranking Profiles (4 tools — entirely new)

Multi-objective scoring strategies — weighted blends over revenue, margin, propensity, engagement, diversity, recency that the ranking engine uses to compute composite PRIE scores.

Tool	Description	Parameters
`listRankingProfiles`	List all ranking profiles. Closes BUG-MCP-ALGO-011…014 — these were entirely missing from MCP before.	—
`createRankingProfile`	Create a new ranking profile (weights map).	`name`: string, `key?`: string (auto-generated from name if omitted), `description?`: string, `weights?`: object (`{ revenue: 0.4, propensity: 0.3, … }`)
`updateRankingProfile`	Update a ranking profile by UUID or name.	`profile`: string, `name?`: string, `description?`: string, `weights?`: object
`deleteRankingProfile`	Soft-delete a ranking profile by UUID or name.	`profile`: 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 (5 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
`updateBehavioralMetric`	Update an existing metric by ID. Closes BUG-MCP-ALGO-009.	`metricId`: string, plus any of: `name`, `description`, `aggregateFunction`, `sourceField`, `windowDays`, `groupByDimensions`, `filterConditions`, `sqlFilter`, `computeMode`, `status`
`deleteBehavioralMetric`	Hard-delete a behavioral metric by ID. Closes BUG-MCP-ALGO-010.	`metricId`: string
`computeMetricNow`	Trigger immediate batch computation for a metric	`metricId`: string
`createMetricRule`	Create a contact policy or decisioning gate 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 (5 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. Closes BUG-MCP-STUDIO-033 — phantom `triggerType`/`status` removed (not in API schema); real fields `definition`, `entryCondition`, `maxDurationDays` added.	`name`: string, `description?`: string, `definition?`: object (`{ nodes, edges }`), `entryCondition?`: object, `maxDurationDays?`: number (1-365, default 30)
`updateJourney`	Update an existing journey by ID or name. Closes BUG-MCP-STUDIO-034.	`journey`: string, plus any of: `name`, `description`, `status`, `definition`, `entryCondition`, `maxDurationDays`
`deleteJourney`	Delete a journey by ID or name. Closes BUG-MCP-STUDIO-035.	`journey`: 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 (5 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
`createSegment`	Create a customer segment (base schema + joins + filters). Closes BUG-MCP-DATA-101.	`name`: string, `baseSchemaId`: string, `description?`: string, `status?`: string, `entityType?`: string, `joins?`: array, `filters?`: array
`updateSegment`	Update an existing segment’s joins or filters by ID or name (name/description are intentionally immutable post-create). Closes BUG-MCP-DATA-102.	`segment`: string, `joins?`: array, `filters?`: array
`deleteSegment`	Soft-delete a segment by ID or name. Closes BUG-MCP-DATA-103.	`segment`: string

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 decisioning gate 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 node 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 decisioning gates 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

createSchema       → Create a "customers" schema
addSchemaField     → Add fields (name, segment, tenure)
createCategory     → Create "Retention" category
createOffer        → Create "Loyalty Upgrade" offer
createChannel      → Create "email" channel
createTreatment    → Create email creative for the offer
createV2DecisionFlow → Create a V2 pipeline
recommend          → Get recommendations for a customer
recordOutcome      → Record the customer's response

Analyze Decision Performance

analyzeOfferPerformance     → See top/bottom performing offers
analyzeQualificationFunnel  → Find where candidates are being filtered out
explainDecision             → Understand why a specific customer got specific offers
simulateRuleChange          → Test impact of loosening a decisioning gate
runHealthCheck              → Full platform health assessment

Build a V2 Pipeline from Scratch

createV2DecisionFlow       → Start with default 4-node pipeline
addV2PipelineNode          → Add "enrich" node to load customer data
addV2PipelineNode          → Add "qualify" node with rules
addV2PipelineNode          → Add "contact_policy" node
updateV2PipelineNodeConfig → Configure scoring method
updateV2PipelineNodeConfig → Set rank method to "diversity"
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	26
Data tools	24
Flow tools	11
Operations tools	8
Studio tools	67
Primitive tools subtotal	162
Agent Playbooks (`playbook_*`) — see Agent Playbooks	10
Total	172

​Overview

​Documentation MCP (Mintlify)

​Connecting to AI Clients

​Rate Limits

​Platform MCP Setup

​Environment Variables

​Quick Setup

​Hosted Endpoint (no local process)

​MCP Resources

​Tool Reference

​Data — Read (5 tools)

​Data — Write (12 tools)

​Data — Utility (1 tool)

​Studio — Read (8 tools)

​Studio — Write

​Studio — Draft Rules (1 tool)

​Studio — Mutations (16 tools)

​Decisioning Gates — Read (1 tool)

​Algorithm — Read (3 tools)

​Algorithm — Write (6 tools)

​Model Management (6 tools)

​Ranking Profiles (4 tools — entirely new)

​Behavioral Metrics — Read (2 tools)

​Behavioral Metrics — Write (5 tools)

​Dashboard & Reporting (2 tools)

​Decisioning (2 tools)

​Decision Traces (2 tools)

​Customer Data (2 tools)

​Journeys (5 tools)

​Interactions & History (1 tool)

​Segments (5 tools)

​Approval Workflow (3 tools)

​Tenant Settings (2 tools)

​Pipeline Runs (2 tools)

​Audit Logs (1 tool)

​Docs Search (1 tool)

​AI Content Generation (2 tools)

​CMS Content Management (7 tools)

​CMS Sync (1 tool)

​Intelligence & Analytics (12 tools)

​Model Intelligence (3 tools)

​V2 Pipeline (9 tools)

​V2 Decision-Flow Transforms (5 tools)

​V2 Pipeline Node Types

​Phase 1 — Narrow

​Phase 2 — Score & Rank

​Phase 3 — Output

​Scoring Methods

​Ranking Methods

​Supported Connector Types

​Contact Policy Rule Types

​Example Workflows

​Create an Offer and Get Recommendations

​Analyze Decision Performance

​Build a V2 Pipeline from Scratch

​Tool Count Summary

Overview

Documentation MCP (Mintlify)

Connecting to AI Clients

Rate Limits

Platform MCP Setup

Environment Variables

Quick Setup

Hosted Endpoint (no local process)

MCP Resources

Tool Reference

Data — Read (5 tools)

Data — Write (12 tools)

Data — Utility (1 tool)

Studio — Read (8 tools)

Studio — Write

Studio — Draft Rules (1 tool)

Studio — Mutations (16 tools)

Decisioning Gates — Read (1 tool)

Algorithm — Read (3 tools)

Algorithm — Write (6 tools)

Model Management (6 tools)

Ranking Profiles (4 tools — entirely new)

Behavioral Metrics — Read (2 tools)

Behavioral Metrics — Write (5 tools)

Dashboard & Reporting (2 tools)

Decisioning (2 tools)

Decision Traces (2 tools)

Customer Data (2 tools)

Journeys (5 tools)

Interactions & History (1 tool)

Segments (5 tools)

Approval Workflow (3 tools)

Tenant Settings (2 tools)

Pipeline Runs (2 tools)

Audit Logs (1 tool)

Docs Search (1 tool)

AI Content Generation (2 tools)

CMS Content Management (7 tools)

CMS Sync (1 tool)

Intelligence & Analytics (12 tools)

Model Intelligence (3 tools)

V2 Pipeline (9 tools)

V2 Decision-Flow Transforms (5 tools)

V2 Pipeline Node Types

Phase 1 — Narrow

Phase 2 — Score & Rank

Phase 3 — Output

Scoring Methods

Ranking Methods

Supported Connector Types

Contact Policy Rule Types

Example Workflows

Create an Offer and Get Recommendations

Analyze Decision Performance

Build a V2 Pipeline from Scratch

Tool Count Summary