The Kelix MCP server

You can register Kelix as an MCP server in any MCP-capable agent — Claude Code, Cursor, Gemini CLI, Kiro — and drive full loop runs, check status, inspect memory, or hit the kill switch entirely through tool calls, without writing a custom adapter.

That wire protocol is proven, not hand-waved. A stdlib-only JSON-RPC server exposes four tools, completes a mock run end-to-end, and sets the kill switch — see tests/test_mcp_server.py and reproduce with pytest tests/test_mcp_server.py -q.

kelix mcp serves Kelix as an MCP server over newline-delimited JSON on stdio. The implementation (src/kelix/mcp_server.py) is deliberately dependency-free: a minimal, auditable JSON-RPC 2.0 loop implementing exactly the subset of MCP needed here — initialize, tools/list, and tools/call (protocol version 2024-11-05). It serves until stdin reaches EOF; malformed lines are ignored; notifications get no response.

kelix mcp                 # serve the current directory's repo
kelix mcp --path DIR      # serve another repo

Registering with Kiro CLI

kiro-cli mcp add --name kelix --command "kelix mcp" --scope workspace

After that, a Kiro session in the workspace can call the four tools below.

The tools

All four tools return a single text content block; errors are reported as a text result with isError: true rather than a protocol failure.

kelix_run

Start a Kelix loop run against the repository. Runs synchronously — the tool call does not return until the run finishes — and returns the run status and a per-iteration summary (rationale and outcome per iteration, plus the diagnosis path if the circuit breaker tripped). Use max_iterations to bound cost.

{
  "type": "object",
  "properties": {
    "max_iterations": {"type": "integer", "minimum": 1},
    "role": {"type": "string", "description": "optional role text"}
  }
}

kelix_status

Show current run/fleet status derived from coordination files: task claims, recent runs, mailbox notes, and the kill switch. Same output as kelix status. Takes no arguments.

{"type": "object", "properties": {}}

kelix_memory

Inspect Kelix’s memory: the project memory file, the recent-episode digest, and the earned-skills digest (see memory-and-skills.md).

{
  "type": "object",
  "properties": {
    "episodes": {"type": "integer", "minimum": 0, "default": 10}
  }
}

kelix_stop

Set the kill switch (.kelix/STOP) so active and future runs halt before their next iteration. Takes no arguments. Remove the file to allow runs again.

{"type": "object", "properties": {}}

Trying it by hand

The wire format is plain enough to poke at without a client — one JSON-RPC request per line on stdin:

printf '%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | kelix mcp

A tool call looks like:

{"jsonrpc":"2.0","id":3,"method":"tools/call",
 "params":{"name":"kelix_run","arguments":{"max_iterations":5}}}