Kiro Conversations MCP

A local MCP server for durable, named Kiro CLI conversations over ACP. Runs are asynchronous, session settings are immutable, and each execution is constrained by the existing macOS filesystem sandbox.

Requirements and commands

• macOS, Node.js 22+, Kiro CLI, and pnpm 11.13.1.
• pnpm build — compile to dist/.
• pnpm test — run unit and MCP API tests.
• pnpm lint / pnpm typecheck — static validation.
• pnpm smoke:live — run the real Kiro ACP smoke test (requires local Kiro authentication).

State defaults to ~/.local/state/kiro-conversations-mcp-acp. Override it per process with KIRO_CONVERSATIONS_ACP_STATE_DIR. Reply persistence can be disabled with KIRO_ACP_PERSIST_REPLIES=0; retained reply size is controlled by KIRO_ACP_MAX_REPLY_BYTES.

Recommended workflow

Use kiro_delegate for the common case. It starts or resumes a named session and waits briefly (10 seconds by default, configurable with KIRO_DELEGATE_WAIT_MS or per-call waitMs, maximum 60 seconds). If the run is still active when the wait expires, the response contains session, runId, current persisted status/phase, elapsed time, and a safe next action. The run remains in the background: delegate never cancels, restarts, or duplicates it on wait expiry.

New sessions require workspace, model, effort, and authority (read_only or workspace_write). Call kiro_models to select a canonical current model ID. The server also normalizes a uniquely resolvable suffix alias such as sol to its canonical ID; ambiguous or unknown values fail before a run starts. These settings are immutable. Existing sessions need only session and message.

For explicit asynchronous control:

1. Call kiro_start; it immediately returns runId and a redacted session summary.
2. Call kiro_wait to wait, or kiro_result to poll.
3. Keep the explicit runId when coordinating multiple calls. It is always supported.

kiro_wait and kiro_result may omit runId only when resolution is deterministic: the session's sole active run, or its latest completed run that has not already been returned. Once an implicit terminal result is consumed, another implicit lookup returns STALE_RUN_ID. Corrupt or otherwise non-unique active state returns AMBIGUOUS_RUN; the server never guesses. Use kiro_status to select an explicit ID.

Tools

• kiro_delegate — start/resume and wait for a short bounded interval without cancelling on expiry.
• kiro_start — durable asynchronous dispatch with a safe session summary.
• kiro_models — canonical model IDs currently available from the local Kiro CLI.
• kiro_wait — bounded wait; optional safely resolved runId.
• kiro_result — non-waiting result; optional safely resolved runId.
• kiro_status — compact dashboard, optionally filtered by session. Immutable model/effort/authority, status, and phase are labeled as persisted. Terminal elapsed time uses persisted start/completion timestamps; active elapsed time uses persisted start plus the response's labeled generatedAt. No ACP semantics are inferred.
• kiro_cancel — explicitly cancel one run and make cancellation durable.
• kiro_sessions — cursor-paginated redacted session summaries.
• kiro_close — cancel active work and close a named conversation without deleting Kiro's internal session.

Result and error safety

Run results use one structured shape across delegate, wait, and result: session, runId, status, known phase, timestamps, elapsedMs, optional structured reply (text, originalBytes, retainedBytes, truncated), optional error, and nextAction. A concise summary is emitted only when one is independently available; the server does not derive claims about files, tests, or commits from reply text.

Tool failures and terminal failures provide a stable code, retryable boolean, safe remediation, and opaque diagnosticId. Diagnostics contain only stable metadata; prompts, replies, internal ACP IDs, and private workspace paths are not logged or returned. kiro_status terminal outcomes omit reply bodies.

Wait expiry is not a run timeout. A running response means only that the bounded wait ended; poll the same runId, wait again, or explicitly cancel it.

Deferred features

This server intentionally does not provide session cloning, elaborate prompt templates, autonomous repair, or a comprehensive activity log.