Kiro Conversations MCP 1.0

A local MCP server for running and coordinating durable Kiro agents over ACP. It is designed for one-task delegation, parallel agent work, resumable conversations, event-driven waiting, and explicit control over execution authority.

Mental model

• A conversation owns durable Kiro context, a workspace, and configurable defaults. Different conversations can run in parallel.

• A run is one message executed in a conversation. It records the exact model, effort, mode, authority, and workspace strategy resolved when the run was created.

• A queued message is a durable future run. Runs are serialized within one conversation and begin in FIFO order.

Conversation defaults can change while the conversation is idle. Existing runs keep their resolved settings.

Related MCP server: MultiService IA

Common workflows

For one task, use kiro_delegate. It creates or continues a conversation and waits for success, failure, cancellation, attention, or the fixed wait ceiling:

{
  "conversation": "new",
  "name": "implement-api",
  "workspace": "/absolute/path/to/project",
  "message": "Implement the API and run the repository checks."
}

The new-conversation defaults are a shared workspace and unrestricted authority. Every response discloses the resolved model, effort, mode, authority, and redacted workspace identity.

For parallel work:

1. Call kiro_spawn once per independent conversation.

2. Preserve every returned conversationId and runId.

3. Make one kiro_wait call with all targets and mode: "any" or "all".

4. Reconcile and independently verify the results.

any returns when one target finishes or needs attention. all returns when all targets finish, but still wakes early if a target needs attention. One wait accepts up to eight explicit targets.

Follow-ups and steering

kiro_send has two delivery modes:

• queue creates a durable run after the active and already queued work.

• interrupt cancels the active run and superseded queued follow-ups, then starts the replacement message.

Interrupt is cancellation followed by a new turn. It is not true mid-inference steering, and the server does not claim otherwise.

Tools

Always use explicit conversationId and runId values after dispatch. IDs are opaque; do not parse or construct them.

Waiting, cancellation, and results

• A run has a fixed 30-minute execution deadline. If it reaches the deadline, it becomes timed_out.

• kiro_delegate and kiro_wait have a fixed 30-minute wait ceiling and no caller-selected duration. They return sooner on completion or attention.

• A wait that reaches its ceiling returns waitExpired: true; it does not cancel nonterminal runs.

• A disconnected or aborted MCP request detaches the caller. Use kiro_wait to reattach, kiro_result for an immediate lookup, or kiro_cancel to stop work deliberately.

• kiro_cancel does not return until bounded ACP shutdown and process-group teardown have completed, so the saved Kiro session is no longer held by that worker.

• kiro_result is permanently idempotent. Reading a result never marks it consumed.

Do not poll reflexively. Spawn parallel work, then use one event-driven multi-target wait.

Attention and permissions

When a tool request requires a decision, the run enters needs_attention; delegate and wait return immediately. Inspect the run and its redacted permission event, then call kiro_permission_decide with the matching conversation, run, and permission request IDs.

Only one-shot decisions are supported:

• allow_once permits this request.

• reject_once rejects this request.

Missing, stale, unknown, or unsupported options fail closed. Unrestricted runs trust all Kiro tools and normally do not request permission.

Execution authority

The default is deliberately unrestricted. It launches Kiro directly on the host with inherited environment, network access, credentials, workspace read/write access, and trust for all tools.

Restricted authority is macOS-only and fails if the sandbox cannot be established. The server never silently falls back to unrestricted or retries a restricted run outside the sandbox. AWS credentials and Kiro agent, steering, and skill roots are readable but not writable. Restricted runs may write only their per-run temporary area, Kiro's settings/session/log and application-support/cache directories, and—in workspace_write mode—the selected workspace.

Authority grants technical capability, not permission to exceed the user’s request. unrestricted does not authorize commits, pushes, deployments, external communications, destructive cleanup, purchases, credential changes, or unrelated work.

Models, effort, mode, and images

Call kiro_capabilities for the live catalog and honor user-specified model, effort, and mode values when they are available. kiro_configure changes conversation defaults only while idle; spawn/send inputs may override settings for one run. Each run permanently records the resolved values.

Image attachments are capability-gated. Send them only when kiro_capabilities.prompt.images is true; otherwise the MCP rejects them as unsupported. When advertised, a prompt accepts up to four absolute local image paths, each with an image MIME type and a declared size of at most 25 MiB.

Available slash commands are discoverable through capabilities, but generic slash-command execution is not exposed in 1.0.

Workspaces and worktrees

shared is the default workspace mode and operates in the supplied directory.

worktree is opt-in. The source must be a clean Git repository root. The server creates a dedicated kiro/<slug>-<short-id> branch and worktree under its state area from the requested base ref. Use kiro_worktree_inspect before integrating or cleaning up.

The MCP never commits, merges, pushes, or deploys automatically. Cleanup refuses active, dirty, conflicted, or unintegrated worktrees and has no force mode. Successful cleanup archives the conversation as retired; it cannot be reactivated because its workspace no longer exists.

Status, retention, and privacy

kiro_status is bounded and cursor-paginated; it does not dump every historical reply. kiro_events is also paginated and retains only redacted phases, plans, tool names/status, workspace-relative locations, usage, permission metadata, mode/config changes, and timestamps.

The server does not expose internal Kiro session IDs, thoughts, prompt bodies, command arguments, tool output, secrets, or absolute workspace paths through status/events. Queued prompt text and image bytes are erased on delivery or whenever the run becomes terminal before delivery. Final replies are retained up to 256 KiB with truncation metadata.

Idle conversations auto-archive after 30 days. Archiving retains state; nothing is automatically deleted. Permanent deletion requires an archived conversation and an exact-name confirmation through kiro_delete.

SQLite state uses WAL mode, foreign keys, a busy timeout, a permission-restricted state directory, and a permission-restricted database file. By default:

~/.local/state/kiro-conversations-mcp/orchestrator-v1.sqlite

Set KIRO_CONVERSATIONS_STATE_DIR in the MCP server environment to relocate the state directory. KIRO_CLI_PATH may select a specific Kiro CLI executable. One process-lifetime ownership lock protects each state directory; a second server fails startup instead of interrupting the first server's live runs. Back up the SQLite database together with its -wal and -shm files while the server is stopped.

Diagnostics use structured, stable error codes and redacted details. Treat the local database as private because it contains conversation metadata and retained final replies. Unrestricted Kiro processes can access the same credentials and services as the MCP process.

Runtime behavior

• Node.js 24 or newer and pnpm are required.

• Kiro ACP engine v2 is used.

• Maximum active conversation workers defaults to four and is bounded from one to eight.

• Excess conversations queue FIFO.

• An idle worker closes after five minutes; the durable conversation remains and resumes or loads on the next run.

• Server restart marks nonterminal runs interrupted while preserving durable state and results.

• Coarse MCP progress notifications are rate-limited and redacted when the client supplies a progress token.

Development and testing

pnpm install --frozen-lockfile
pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm test:integration:kiro
pnpm smoke:live

Testing is tiered:

• pnpm test runs deterministic offline unit, state-machine, SQLite, state-ownership, authority, worktree, ACP-fake, schema, progress, and orchestration tests.

• pnpm test:integration:kiro builds and exercises the production MCP entry point with capability discovery, one authenticated unrestricted real-Kiro ACP turn, and durable idempotent result reads.

• pnpm smoke:live builds and exercises the production MCP entry point with:

  • parallel independent conversations, overlapping execution, and multi-target wait-any/wait-all;

  • a queued context-dependent follow-up, idempotent result reads, and idle authority configuration;

  • active-run interrupt/replacement, explicit durable cancellation, and active-run restart recovery against the same SQLite state;

  • unrestricted command write/read, bounded redacted status/events, archive filtering, and durable conversation visibility after restart;

  • on macOS, read_only execution plus workspace_write one-shot permission decisions and a verified disposable write;

  • image prompting only when live capabilities advertise it, otherwise an explicit SKIP;

  • disposable Git worktree creation, clean inspection, and safe cleanup.

The live smoke does not replace deterministic negative-path tests. Sandbox confinement, dirty/active/unmerged worktree cleanup refusal, schema limits, and unsupported-capability behavior remain in the offline suite because they are more reliable there than when driven by model choices.

The live tiers require an installed, authenticated Kiro CLI and may consume model quota. They isolate MCP state and all workspaces under a disposable temporary directory and print only redacted PASS, SKIP, failure-code, and provenance lines. Their default whole-process deadlines are 10 minutes for integration and 25 minutes for smoke; override them with positive-integer KIRO_GREENFIELD_INTEGRATION_DEADLINE_MS and KIRO_GREENFIELD_SMOKE_DEADLINE_MS values. Validate the production build and inspect the capability response before treating a release as ready.