Kiro MCP Server

New Kiro session

kiro_session_new

Start a Kiro CLI V3 session in a workspace and attach it to this server; optionally set agent mode, model, effort, or create a cloud sandbox session.

Instructions

Create a Kiro CLI V3 session (session/new) in a workspace inside KIRO_MCP_ROOTS and attach it to this server. Optionally pick the agent mode (vibe, plan, spec, quick-spec, bug-fix, autonomous, or a custom agent), model, and effort; values Kiro did not apply are listed in warnings. execution_target cloud creates a cloud sandbox session on the given repos. Caller-supplied MCP servers are never accepted. Also how to compose /clear (start a new session) and /spawn (a new session plus kiro_prompt).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "cwd": "<cwd>"
    },
    "name": "kiro_session_new"
  }
}

Input Schema

Name	Required	Description
`cwd`	Yes	Workspace directory, inside KIRO_MCP_ROOTS (relative paths resolve against the first root).
`mode`	No	Initial agent mode id, as advertised by Kiro.
`model`	No	Initial model id.
`repos`	No	owner/name repositories for a cloud session.
`title`	No	Session title, set with _kiro/session/rename.
`effort`	No	Initial effort level, when the model supports it.
`execution_target`	No	`cloud` runs the session in a Kiro cloud sandbox.
`additional_directories`	No

Output Schema

Name	Required	Description	Default
`modes`	Yes
`title`	Yes
`cursor`	Yes
`commands`	Yes
`warnings`	Yes
`session_id`	Yes
`current_mode`	Yes
`context_usage`	Yes
`config_options`	Yes
`execution_target`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.1Nov 5, 2026

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, the description discloses two non-obvious behaviors: 'Caller-supplied MCP servers are never accepted' (a hard security boundary the agent cannot infer from the schema, which has additionalProperties false but no mcp field) and that silently rejected values surface in `warnings`. It also clarifies that cloud execution happens on the given repos. It does not describe what state is created on the local filesystem or any limits, but the annotation set already covers mutation/open-world character.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The first two sentences are dense and front-loaded with the essential creation contract and the warnings/deprecation behavior. The final sentence, 'Also how to compose /clear ... and /spawn ...', is a dangling fragment that promises composition guidance without delivering it, which is wasted space and slightly misleading.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description need not explain return values, and an output schema plus 88% param coverage carries most of the weight. The description covers the main risk areas for this 8-param mutating tool: workspace root confinement, cloud vs local target, mode/model/effort selection, and the warnings channel for rejected values. The only shortfall is the unfinished composition sentence, which leaves a promised workflow hint unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 88%, so the baseline is 3. The description does add real meaning the schema lacks: the concrete mode values (vibe, plan, spec, quick-spec, bug-fix, autonomous, custom agent) versus the schema's circular 'as advertised by Kiro', and it ties `repos` to the cloud target and `effort` to model support. It adds nothing for title or additional_directories beyond what the schema says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('Create a Kiro CLI V3 session (session/new)') plus its scope constraint (workspace inside KIRO_MCP_ROOTS, attached to this server), which is far more precise than the title alone. It implicitly separates itself from load/fork siblings by framing this as creation of a fresh session, though it never names kiro_session_load or kiro_session_fork as the alternatives for attaching to or branching an existing session.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is genuine conditional guidance for one branch: execution_target `cloud` creates a sandbox session on the given repos, so an agent knows when to pass `repos`. The closing sentence gestures at decision guidance ('how to compose /clear ... and /spawn ...') but states that guidance exists rather than giving it, and no sibling (session_load, session_fork, stream_session) is named as a when-not alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.