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 another set of tools — the same way dbt, Snowflake, and Atlan expose theirs.

​
What’s exposed

The server registers 172 tools across six primitive modules + a playbook layer. Counts verified against the actual MCP tool registrations and the bundled playbook definitions.

​
Running the server

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

​
Auth

The server reads KAIREON_API_KEY and KAIREON_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.
KAIREON_API_KEY must be a control-plane-scoped key. The MCP server’s tools call management endpoints (/api/v1/schemas, /api/v1/decision-flows, /api/v1/algorithm-models, /api/v1/content, …), which are control-plane surfaces. A default data-plane-only key gets 403 on those calls. Mint the key with scopes: ["control-plane"] (admin only; see API Keys) and keep it internal — it is a management credential.

​
Hosted endpoint (no local process)

Remote agents can use the same tool surface without running the stdio process: POST /api/v1/mcp is a stateless JSON-RPC endpoint supporting initialize, ping, tools/list, and tools/call.
  • Auth — the standard API-key ladder: send X-API-Key and X-Tenant-Id headers. The hosted MCP endpoint is a control-plane surface, so the key must be minted with the control-plane scope (admin only; a default data-plane-only key gets 403 — see API Keys). Keep the key internal — it is a management credential; never embed it in client apps. Rate limited to 60 calls/min; every tools/call is audit-logged.
  • Tenant pinning — the authenticated tenant overwrites any tenantId argument in tool calls; a key for one tenant can never reach another.
  • Governed playbooks — on the hosted (governed) surface, no mutating playbook writes directly. playbook_promote_challenger_if_winning and playbook_rebuild_offer_qualification queue an experiment / rule recommendation for admin/four-eyes approval; playbook_run_shadow_experiment, playbook_arbitrate_policy_conflict, and playbook_bootstrap_new_offer_campaign fail-closed (return governed: true, dryRun: true and make no change). Direct writes on apply: true only happen on the ungoverned first-party (stdio) surface.
  • The production read-only default below applies to the hosted surface too.

​
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

​
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 audit-log 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