Skip to main content
KaireonAI ships an MCP (Model Context Protocol) server that exposes the platform’s data, decisioning, and pipeline surfaces as tools any MCP-aware AI assistant can call. From an external agent’s perspective, KaireonAI is just another set of tools — the same way dbt, Snowflake, and Atlan expose theirs.

​
What’s exposed

The server registers six tool modules. Counts shown are the production-stable tools as of Phase 2b.
ModuleToolsHighlights
Flow (Phase 2b)11Create/update/run IR-native pipelines, version history, run-error inspection, replay, customer scoring
Data18Schemas, connectors, transform-type catalog, raw data ops
Studio30+Offers, decision flows, qualification rules, channels, journeys, contact policies, creates + updates
AlgorithmsseveralModels, training, predictors
Operations8Alerts, audit log, approvals, tenant settings
AIseveralAI configuration helpers
Plus a set of playbooks (multi-step workflows the agent can invoke).

​
Running the server

cd platform
npm install
npm run mcp
The server uses the stdio transport — point your MCP client (Claude Desktop, Cursor, etc.) at the npm run mcp command.

​
Auth

The server reads KAIREONAI_API_KEY and KAIREONAI_TENANT_ID from the environment and forwards them as X-API-Key + X-Tenant-Id on every HTTP call to /api/v1/*. Provision a krn_* tenant key in Settings → Integrations → API Keys and export it before launching.

​
Read-only by default in production

Write tools (createFlowPipeline, updateFlowPipeline, runFlowPipeline, replayFlowRun, testFlowConnector, scoreCustomer, plus all writes in other modules) are disabled in production unless MCP_ALLOW_WRITES=true is set. Calling a blocked tool returns a structured error explaining the gate. Read tools always work.

​
Phase 2b: Flow tools

ToolVerbPurpose
createFlowPipelinewriteCreate an IR-native pipeline. Body: { name, connectorId, schemaId, ir }. The server validates ir via parsePipelineIR before persistence.
getFlowPipelineIrreadReturn the latest IR document for a pipeline. 409 if the pipeline is still in legacy node/edge format.
updateFlowPipelinewriteSave a new IR version against an existing pipeline. Auto-promotes legacy pipelines to IR-native on first save.
listFlowPipelineVersionsreadIR version history (desc by version) — version, authoredBy, comment, createdAt.
runFlowPipelinewriteTrigger a run. IR-native pipelines dispatch in-process via runBatch; legacy pipelines go to the BullMQ worker queue.
listFlowRunsreadRecent runs for a pipeline.
inspectFlowErrorreadError context for a specific run — supports AI-driven self-healing workflows.
replayFlowRunwriteRe-run a pipeline from a previous run id.
testFlowConnectorwriteTest connection ping for a connector — verifies credentials + reachability.
createYamlConnectorstubDocumented surface for Phase 5; currently returns { status: "deferred", phase: "5" }.
scoreCustomerwriteWraps POST /api/v1/recommend so external agents can score customers via MCP.

​
Decisioning primitives (existing)

Already exposed by studio-tools.ts and reusable directly by external agents:
  • listOffers, createOffer, updateOffer
  • listDecisionFlows, createDecisionFlow, updateDecisionFlow
  • listQualificationRules, createQualificationRule
  • listChannels, listContactPolicies, listJourneys, getJourney, listInteractions, plus more
This means an external agent has full read + (gated) write access to the decisioning model — first-party MCP for Next-Best-Action.

​
Validation contract

Every IR-native write goes through three checks server-side:
  1. HTTP body validation — Zod schemas on each route.
  2. parsePipelineIR — Phase 1 two-phase validator (Zod schema + structural acyclic + ref-integrity).
  3. Audit logging — every write writes an AuditLog row. AI-authored writes additionally land under entityType='pipeline_ai_proposal'.
Invalid IR is rejected with HTTP 400 and a structured errors array the agent can use to retry with a corrected proposal — same contract the in-app AI Pipeline Mode (Phase 2a) uses.

​
Roadmap

PhaseWhat this gets
2b (this page)11 Flow tools live; existing decisioning tools documented as part of the unified surface.
5YAML connector authoring lights up createYamlConnector for real.
FutureStreamable HTTP transport (currently stdio only); MCP Apps registry submission.