# 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.

## 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:

```json
{
  "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

| Tool | Use it when |
| --- | --- |
| `kiro_capabilities` | Discover the installed Kiro CLI version and model catalog together with the MCP’s current ACP v2 feature envelope, authorities, defaults, and limits. Use `refresh: true` before making a model choice that must be current. |
| `kiro_spawn` | Start work asynchronously and receive durable conversation/run IDs immediately. Use separate conversations for parallel work. |
| `kiro_delegate` | Handle the common single-task flow: spawn and wait in one call. |
| `kiro_wait` | Wait event-first on one to eight explicit runs using `any` or `all`; use it after spawning parallel work or reconnecting. |
| `kiro_send` | Queue a follow-up or explicitly interrupt and replace current work. |
| `kiro_result` | Read one run’s current or terminal result immediately. Reads are idempotent and never consume the result. |
| `kiro_status` | Browse bounded, cursor-paginated conversation summaries and counts, optionally filtered by state, run status, workspace fingerprint, model, authority, or archive state. |
| `kiro_events` | Inspect cursor-paginated, redacted activity for one explicit run. |
| `kiro_permission_decide` | Resolve a current attention request with `allow_once` or `reject_once`. |
| `kiro_configure` | Change model, effort, mode, or default authority while a conversation is idle. |
| `kiro_fork` | Fork a durable Kiro conversation only when live capabilities advertise session forking and the ACP client supports it. |
| `kiro_cancel` | Explicitly cancel one run. Cancelling a waiter or disconnecting does not cancel Kiro. |
| `kiro_archive` | Hide an idle conversation from normal active use while retaining its history. |
| `kiro_delete` | Permanently remove local MCP state for an archived conversation using its exact name as confirmation. |
| `kiro_worktree_inspect` | Review an isolated worktree’s branch, base, active-run count, changed files, merge state, and bounded diff statistics. |
| `kiro_worktree_cleanup` | Remove a clean, inactive, already integrated worktree and its branch. It has no force option and never merges. |

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.

| Authority | Isolation and access |
| --- | --- |
| `unrestricted` | Direct host process, inherited environment, network enabled, workspace read/write, all Kiro tools trusted. |
| `workspace_write` | macOS sandbox, network enabled, workspace read/write, filesystem reads pretrusted; other requests may require one-shot attention. |
| `read_only` | macOS sandbox, network enabled, workspace read-only, filesystem reads pretrusted; other requests may require one-shot attention. |

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:

```text
~/.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

```bash
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.