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.
Prerequisites
Section titled “Prerequisites”kora serve must be running on the same profile. Without it every tool fails with a guided error (start kora serve first).
Register it in an MCP host
Section titled “Register it in an MCP host”Point your host at the binary. For Claude Code:
claude mcp add kora -- kora mcp-control # dev profile: kora --dev mcp-controlGeneric 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.
Typical agent loop
Section titled “Typical agent loop”kora_sessionsorkora_session_new→ pick asessionIdkora_session_send→{accepted:true}kora_session_wait→{done:true, outcome:"done", text:"…"}, or pollkora_session_events- If
pendingis non-empty →kora_session_approve/kora_session_answer, then wait again
Troubleshooting
Section titled “Troubleshooting”- Tool error “no kora serve on this profile” → start
kora servefirst; check--devconsistency between serve and the MCP command line. kora_session_waitreturnsdone:false→ the turn is still running pasttimeoutMs; call it again or inspectkora_session_events.session writer slot heldon send → a terminal has the session attached as writer; detach it or pick another session.- Turn ends but
textis empty → checkkora_session_events.result.error— the provider may have failed (missing key, exhausted quota). - Tool calls never appear in the host → verify
tools/listshows the ninekora_*tools; if not, the MCP process failed to start — runkora mcp-controlby hand and check stderr.