kernelmcp

The sovereign orchestrator -- connects all MCP AI suite libraries into an autonomous agent

Part of the MCP AI Suite.

Features

• ReAct engine with autonomous Thought-Action-Observation loop driven by LLM
• LTP (Lean Task Protocol) compiler turns goals into deterministic execution plans in one LLM call
• Dry-run / simulation -- kernel.run(goal, dry_run=True) plans without executing any tool (no side effects); records the tool calls it would make. Also kernelmcp run --dry-run. The LLM still runs, so tokens are still spent.
• A/B testing of constitutions -- run_ab(...) runs a goal under two constitutions and reports success/cost/token deltas + a winner (CLI kernelmcp ab, MCP tool ab_test, API POST /ab)
• Deterministic graph nodes -- a graph node can run a governed tool or sandboxed Python (tool/code node), not just an LLM agent. Runs through the tool chokepoint (budget/audit/DLP), no LLM; ${input} consumes the upstream node's output. Same engine and visual editor as agent graphs
• Dynamic map-reduce (map node) -- fan out a body (tool / code / agent) over a runtime-determined list and reduce the results -- the parallel width is decided at execution time, not drawn in the graph. over resolves a parent's output / a ${channel:NAME} to a list; each branch sees ${item}/${index}; results are merged by a named reducer (append/concat/sum/dedup/last/merge) into the node output and an optional named into channel. Each branch is a governed, spanned step (its tool calls hit the same chokepoint). Governance note: the graph path has no static plan verifier (unlike compiled LTP plans), so dynamic fan-out is bounded at runtime -- a per-node max_fanout (hard-ceilinged) plus per-call budget/quota -- rather than statically proven. Use the LTP path when you need a statically verifiable plan
• Programmatic graph API -- build cyclic, stateful agent graphs in pure Python (from kernelmcp.graph import Graph, END): add_node(name, fn) runs an arbitrary Python callable that shares a state dict, add_edge(a, b) (a self-edge is a bounded loop with an early-exit {"__stop__": True} signal), add_conditional_edge(src, router, mapping) for branching, plus checkpoint/resume (GraphCheckpointer) that snapshots execution per wave. It's a thin facade over the same executor as the visual builder, so parallel waves, governed tool/code nodes, per-node spans and map-reduce all work unchanged. Note: callable nodes are your own in-process code (like a LangGraph node) -- not sandboxed and not through the tool chokepoint (governance still applies to any kernel tools they call); use a code node for sandboxed execution. Graphs with Python callables are library-only by nature (a function can't cross JSON/MCP/HTTP)
• Suite orchestration -- wires websearchmcp, sandboxmcp, workspacemcp, planningmcp, schedulermcp, memorymcp, and ragmcp in-process
• Smart routing -- TaskSupervisor selects cloud, local, or fast model per task complexity
• Sub-agent system -- spawn specialized agents (code, research, file, memory) for subtasks
• Budget enforcement with per-task and per-namespace token/cost caps
• DLP secret guard -- redacts secrets (AWS keys, tokens, private keys, connection strings) in tool results before they reach the model, and blocks outbound tool calls whose arguments carry a secret. Enforced at the tool chokepoint -- deterministic, not asked of the model. Opt-in via enable_dlp; emits secret.redacted / secret.blocked events
• Agent-JIT cache (experimental, situational) -- amortizes repeated task families: the first instance reasons normally and its execute_code solution is cached by a semantic signature; a later instance is validated once by shadow execution (cached pattern vs cold engine, outputs compared deterministically) and then reused. When it engages, a reuse measured ~34× cheaper (~330 vs ~11k tokens) and never ships an unvalidated answer (falls back to the full engine on mismatch). Honest caveat: the gain is only net-positive on repetitive workloads that reliably route through execute_code — engagement hinges on that, which is non-deterministic for simple tasks, so on low-repetition or non-code-routed traffic it can be net-neutral to ~+15% (an un-amortized shadow pass). Hence off by default. Opt-in via jit=True / KERNELMCP_JIT; inspect with kernel.jit_stats()
• Circuit breaker and fallback chain for resilient LLM calls with automatic retry and backoff
• Full audit trail via SQLite -- every tool call, cost, and token count logged
• Prometheus metrics -- a /metrics endpoint on the kernel API (and the Hub) exposes tool-call counts + success rate + duration, tasks by status, tokens and cost. Instrumented at the single governed tool chokepoint, so every execution path is covered. Opt-in via the [metrics] extra (pip install mcpaisuite-kernelmcp[metrics]); a graceful no-op (empty exposition) when prometheus-client isn't installed
• OpenTelemetry export -- KernelFactory.create(otel_endpoint="http://localhost:4317") exports each finished task's live span tree (parent/child, tokens/cost/model attributes) to any OTLP backend (Jaeger, Zipkin, Grafana Tempo). Opt-in via the [tracing] extra; a graceful no-op when the OTel SDK isn't installed or no endpoint is set
• Event bus for real-time streaming and progress callbacks
• Elicitation -- agent can pause execution to ask user questions
• Self-hosted Hub connector -- connect_hub() reports an embedded kernel's traces to your own Hub for monitoring, with opt-in remote control (ping/stats/set_config/run/cancel) over an outbound-only connection

Installation

pip install mcpaisuite-kernelmcp
# Optional extras:
pip install mcpaisuite-kernelmcp[dev]          # Development tools
pip install mcpaisuite-kernelmcp[all]          # All suite libraries + webhooks + REST API
pip install mcpaisuite-kernelmcp[memorymcp]    # Memory integration
pip install mcpaisuite-kernelmcp[sandboxmcp]   # Sandbox integration
pip install mcpaisuite-kernelmcp[planningmcp]  # Planning integration

Setup (interactive)

kernelmcp init   # pick model, API key, and libraries -> writes kernelmcp.config.yaml
kernelmcp start --config kernelmcp.config.yaml

Quick Start

from kernelmcp import KernelFactory

kernel = KernelFactory.from_env()
task = await kernel.run("Research the latest Python 3.13 features and summarize them")
print(task.summary)
print(f"Cost: ${task.total_cost:.4f}, Tokens: {task.total_tokens}")

MCP Server

# Agent mode (kernel LLM drives the ReAct/LTP loop):
kernelmcp start --transport stdio --mode agent

# Router mode (client LLM drives tool selection, kernel routes):
kernelmcp start --transport stdio --mode router

# SSE transport:
kernelmcp start --transport sse --port 8080

Configuration

Or configure via YAML:

llm_model: claude-sonnet-4-6
enable_routing: true
max_turns: 20
memory:
  episodic_store: sqlite
workspace:
  root_path: /data/workspace
sandbox:
  enable_host_access: true

kernel = KernelFactory.from_yaml("config.yaml")

Kubernetes (Helm)

A Helm chart under helm/kernelmcp deploys the HTTP API server (kernelmcp-api, exposing /health and Prometheus /metrics) with probes, a config ConfigMap, an optional API-key Secret, optional bundled Redis, Ingress, and HPA.

# Build the image (no image is published yet) and load/push it where your cluster can pull it:
docker build -t kernelmcp:1.0.5 .
# kind load docker-image kernelmcp:1.0.5      # for a local kind cluster

# Install (set your provider key; a Secret is created for it):
helm install kernel ./helm/kernelmcp \
  --namespace kernelmcp --create-namespace \
  --set llm.model=claude-sonnet-4-6 \
  --set llm.apiKey=$ANTHROPIC_API_KEY

# Optional: bundled Redis, Ingress, autoscaling
helm upgrade kernel ./helm/kernelmcp --reuse-values \
  --set redis.enabled=true --set ingress.enabled=true --set autoscaling.enabled=true

# Verify
kubectl -n kernelmcp port-forward svc/kernel-kernelmcp 8000:8000
curl localhost:8000/health

Use an existing Secret instead of an inline key with --set llm.existingSecret=my-secret --set llm.existingSecretKey=api-key. See helm/kernelmcp/values.yaml for all options. (Raw k8s manifests also live in k8s/ if you prefer kubectl apply.)

Self-Hosted Hub (Monitoring & Control)

Embed kernelmcp in your own app and point it at a self-hosted Hub to monitor your kernels from one place -- and optionally control them. Monitoring is telemetry push over an outbound-only connection (no inbound port on your app); control is opt-in.

from kernelmcp import KernelFactory, connect_hub

kernel = KernelFactory.from_env()

# Monitoring only (always on once connected):
await connect_hub(kernel, hub_url="http://my-hub:8007", project="prod", api_key="kmh_...")

# ...or also let the Hub send commands to this kernel (opt-in):
await connect_hub(kernel, hub_url="http://my-hub:8007", project="prod",
                  api_key="kmh_...", allow_control=True)

# Use the kernel normally -- finished tasks show up in your Hub.

connect_hub(...) is fail-safe and a no-op if unconfigured (it also reads KERNELMCP_HUB_URL / KERNELMCP_HUB_KEY / KERNELMCP_HUB_PROJECT from the environment), so it is always safe to call unconditionally. With allow_control=True the Hub can send ping / stats / set_config / run / cancel commands; pass run_handler(goal) to customize how run executes. Returns a HubConnector (or None if unconfigured); call await connector.stop() to disconnect.

API Reference

KernelPipeline

The main orchestrator managing tasks, budgets, and all suite libraries.

await kernel.run(goal, namespace="default", mode="", budget_usd=None, constitution=None)
await kernel.call_tool(tool_name, arguments, namespace="default")
await kernel.spawn_agent(agent_type, task, namespace="default", max_turns=None)
await kernel.get_stats()
await kernel.health()

KernelFactory

KernelFactory.default()             # Minimal kernel, no integrations
KernelFactory.from_env()            # Build from environment variables
KernelFactory.from_yaml("cfg.yaml") # Build from YAML config
KernelFactory.full_suite()           # All libraries wired in-process
KernelFactory.create(llm_model=..., memory_pipeline=..., ...)  # Full control

Architecture

KernelPipeline wraps a ReActEngine that drives the Thought-Action-Observation loop. A SuiteOrchestrator holds references to all sub-library pipelines (memory, workspace, sandbox, planning, scheduler, RAG) and exposes their tools to the engine. TaskSupervisor routes each task to the appropriate LLM model (cloud, fast, or local) based on complexity, while BudgetEnforcer and CircuitBreaker provide cost control and resilience.

Testing

pip install -e ".[dev]"
pytest tests/ -v

License

Apache-2.0 — see LICENSE.

Open source for individuals and open-source projects. For commercial use in closed-source products, a commercial license is available — contact contact@mcpaisuite.com.