Skip to content

MCP control tools

kora mcp-control is an MCP server on stdio (server name kora-control) that exposes Kora sessions as tools. It is a client of the profile’s kora serve socket — writer slots, approvals and turn events all stay on the single control plane; it never runs a second engine.

kora serve must be running on the same profile. Without it every tool fails with a guided error (start kora serve first).

Point your host at the binary. For Claude Code:

Terminal window
claude mcp add kora -- kora mcp-control # dev profile: kora --dev mcp-control

Generic MCP JSON config:

{ "mcpServers": { "kora": { "command": "kora", "args": ["mcp-control"] } } }

Kora itself can consume it too — add the same entry to mcpServers in your profile settings and its tools appear as mcp_kora_kora_session_*.

Tool Args Does
kora_sessions — List sessions: id, title, provider, model, folders, plus live busy/writer/viewers
kora_session_new cwd? Create a session, return {sessionId}; cwd defaults to the serve process cwd
kora_session_send sessionId, text Claim the writer slot (once) and start a turn. Non-blocking: {accepted:true}
kora_session_wait sessionId, timeoutMs? Block until the next turn result → {done, outcome, turnId, text}. Default 30000 ms, capped at 300000 ms; returns {done:false,busy} past it
kora_session_events sessionId Compact snapshot: busy, assembled text, pending approvals/inputs, last result, recent event kinds
kora_session_approve sessionId, toolCallId, decision allow runs once, always switches the session to build mode, deny refuses
kora_session_answer sessionId, toolCallId, value Answer a pending user-input request
kora_session_steer sessionId, text Inject steering text mid-turn
kora_session_cancel sessionId Abort the in-flight turn
kora_session_kill sessionId Drop every serve attachment of the session — the writer’s turn is cancelled, viewers are notified and unsubscribed. tmux chat wraps are killed from the TUI settings Live tab instead

toolCallId comes from the pending entries of kora_session_events. kora_session_send claims the writer slot the first time per session — it fails if a human (or another agent) holds it via kora attach.

  1. kora_sessions or kora_session_new → pick a sessionId
  2. kora_session_send → {accepted:true}
  3. kora_session_wait → {done:true, outcome:"done", text:"…"}, or poll kora_session_events
  4. If pending is non-empty → kora_session_approve / kora_session_answer, then wait again
  • Tool error “no kora serve on this profile” → start kora serve first; check --dev consistency between serve and the MCP command line.
  • kora_session_wait returns done:false → the turn is still running past timeoutMs; call it again or inspect kora_session_events.
  • session writer slot held on send → a terminal has the session attached as writer; detach it or pick another session.
  • Turn ends but text is empty → check kora_session_events.result.error — the provider may have failed (missing key, exhausted quota).
  • Tool calls never appear in the host → verify tools/list shows the nine kora_* tools; if not, the MCP process failed to start — run kora mcp-control by hand and check stderr.