> ## Documentation Index > Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt > Use this file to discover all available pages before exploring further. # MCP Flow Server > Operate the KaireonAI decisioning + pipeline platform from any MCP-aware AI assistant — Claude Desktop, Cursor, downstream agents. 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. | Module | Tools | Highlights | | ------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Flow** | 11 | Create/update/run IR-native pipelines, version history, run-error inspection, replay, customer scoring | | Data | 24 | Schemas (incl. inbound-FK probe + alter-column via updateSchemaField), connectors (full CRUD), segments, transform-type catalog, raw data ops | | Studio | 67 | Offers, decision flows, decisioning gates, channels, journeys, contact policies, triggers, guardrails, **category CRUD (incl. updateCategory + deleteCategory)** | | Algorithms | 26 | Models, training, predictors, experiments, ranking profiles, behavioral metrics | | Operations | 8 | Alerts, audit log, approvals, tenant settings | | AI | 26 | AI configuration helpers, Pipeline Mode coordinator entry points | | **Playbooks** | 10 | Multi-step workflows: `bootstrap-new-offer-campaign`, `rebuild-offer-qualification`, `promote-challenger-if-winning`, `audit-tenant-data-health`, `run-shadow-experiment`, `explain-decision-chain`, `generate-dsar-export`, `simulate-weight-change`, `explain-algorithm-upgrade`, `arbitrate-policy-conflict` | ## Running the server ```bash theme={null} 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 `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](/api-reference/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](/api-reference/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 | Tool | Verb | Purpose | | -------------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `createFlowPipeline` | write | Create an IR-native pipeline. Body: `{ name, connectorId, schemaId, ir }`. The server validates `ir` via `parsePipelineIR` before persistence. | | `getFlowPipelineIr` | read | Return the latest IR document for a pipeline. 409 if the pipeline is still in legacy node/edge format. | | `updateFlowPipeline` | write | Save a new IR version against an existing pipeline. Auto-promotes legacy pipelines to IR-native on first save. | | `listFlowPipelineVersions` | read | IR version history (desc by version) — version, authoredBy, comment, createdAt. | | `runFlowPipeline` | write | Trigger a run. IR-native pipelines dispatch in-process via `runBatch`; legacy pipelines go to the BullMQ worker queue. | | `listFlowRuns` | read | Recent runs for a pipeline. | | `inspectFlowError` | read | Error context for a specific run — supports AI-driven self-healing workflows. | | `replayFlowRun` | write | Re-run a pipeline from a previous run id. | | `testFlowConnector` | write | Test connection ping for a connector — verifies credentials + reachability. | | `createYamlConnector` | write | Validate a YAML connector spec and register it in the in-process connector registry. Returns the parsed spec (`id`, `displayName`) on success, or `{ ok: false, errors }` on a bad spec. | | `scoreCustomer` | write | Wraps `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 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 | Phase | What this gets | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 2b (this page) | 11 Flow tools live; existing decisioning tools documented as part of the unified surface. | | 5 | Durable YAML connector authoring — today `createYamlConnector` validates + registers a spec in the in-process registry; Phase 5 persists it across processes. | | Future | Streamable HTTP transport (currently stdio only); MCP Apps registry submission. | ## Related * [Pipeline IR](/data/transforms/pipeline-ir) — the typed document Flow tools operate on. * [AI Pipeline Authoring](/ai-ml/ai-pipeline-authoring) — in-app sibling that produces IR via natural language. * [Pipelines API](/api-reference/pipelines) — REST endpoints these tools wrap.