Kiro CLI — Tool System¶
Built-in tools¶
Canonical names with aliases:
| Canonical | Alias | Purpose |
|---|---|---|
fs_read |
read |
File read |
fs_write |
write |
File write |
execute_bash |
shell |
Shell/bash execution |
use_aws |
aws |
AWS CLI integration |
No exhaustive built-in catalog is published; tools are documented implicitly via hook matchers and agent examples. Default behavior: all tools available, confirmation required for most operations.
Permission / allow-deny model¶
Five overlapping mechanisms:
- Agent
tools— whitelist of tool names the agent may use. - Agent
allowedTools— pre-approved tools that run without confirmation. - MCP
autoApprovearray — tool names that bypass prompting;["*"]= all. - MCP
disabledToolsarray — tool names to omit entirely from that server. - MCP
disabled: true— disable the whole server without removing config.
Hook matcher selectors: @builtin (all built-ins), @git (all tools from a named MCP server), @git/status (a specific MCP tool), * (all tools), or no matcher (all tools).
Custom tools¶
Kiro has no user function-call tool API and no slash-command authoring API. Extensibility comes through:
Custom agents (primary mechanism)¶
JSON files.
| Scope | Path |
|---|---|
| Global | ~/.kiro/agents/<name>.json |
| Workspace | .kiro/agents/<name>.json |
Creation: /agent create my-agent (AI-assisted) or --manual; kiro-cli agent create my-agent; /agent create my-agent --from existing-agent.
Schema:
{
"name": "my-agent",
"description": "A custom agent",
"tools": ["read", "write"],
"allowedTools": ["read"],
"resources": [
"file://README.md",
"file://.kiro/steering/**/*.md",
"skill://.kiro/skills/**/SKILL.md"
],
"prompt": "You are a helpful coding assistant",
"model": "claude-sonnet-4",
"mcpServers": { "fetch": { "command": "fetch3.1", "args": [] } },
"includeMcpJson": false,
"hooks": {}
}
| Field | Type | Description |
|---|---|---|
name |
string | Agent identifier |
description |
string | Human description |
tools |
array | Whitelist of tool names |
allowedTools |
array | Tools auto-approved without prompting |
resources |
array | Files/globs/skills injected into context (file://, skill://) |
prompt |
string | System prompt |
model |
string | Model override (e.g. claude-sonnet-4) |
mcpServers |
object | MCP servers scoped to this agent |
includeMcpJson |
boolean | Whether to also include workspace/user mcp.json servers |
hooks |
object | Hook configuration |
Reserved built-in agents (cannot be edited): kiro_default, kiro_help, kiro_planner.
Hooks (lifecycle scripting)¶
Defined inside the agent config. Events: agentSpawn, userPromptSubmit, preToolUse, postToolUse, stop.
Stdin payload:
{
"hook_event_name": "preToolUse",
"cwd": "/current/dir",
"session_id": "abc123",
"tool_name": "read",
"tool_input": { "operations": [{ "mode": "Line", "path": "..." }] }
}
Exit-code semantics:
preToolUseexit2→ block tool execution; STDERR returned to the LLM.stopstdout JSON{"decision":"block","reason":"..."}→ agent continues instead of stopping.- exit
0→ success.
Steering files¶
Persistent project context. .kiro/steering/*.md (workspace) or ~/.kiro/steering/*.md (global). Foundational files: product.md, tech.md, structure.md. AGENTS.md (workspace root or ~/.kiro/steering/) is always included.
Custom agents do NOT auto-load steering
Only the default kiro_default agent auto-loads steering. Custom agents must declare it explicitly: "resources": ["file://.kiro/steering/**/*.md"].
MCP tools¶
| Scope | Path | Format |
|---|---|---|
| Workspace | <project>/.kiro/settings/mcp.json |
JSON |
| User/global | ~/.kiro/settings/mcp.json |
JSON |
Both merge when present; workspace takes precedence at the server-name key level (no field-level merge).
Schema¶
{
"mcpServers": {
"local-server": {
"command": "uvx",
"args": ["awslabs.aws-documentation-mcp-server@latest"],
"env": { "API_KEY": "hard-coded", "OTHER": "${SHELL_ENV_VAR}" },
"disabled": false,
"autoApprove": ["tool1", "tool2"],
"disabledTools": ["tool3"]
},
"remote-server": {
"url": "https://api.example.com/mcp",
"headers": { "Authorization": "Bearer token" },
"oauth": { "clientId": "your-app-client-id", "redirectUri": "127.0.0.1:8080" },
"oauthScopes": ["read", "write"],
"disabled": false,
"autoApprove": ["*"],
"disabledTools": ["danger-tool"]
},
"typed-http": {
"type": "http",
"url": "https://api.example.com/mcp",
"oauth": { "redirectUri": "127.0.0.1:8080", "oauthScopes": ["read", "write"] }
}
}
}
Local server: command (req), args (req), env (${VAR} expansion), disabled, autoApprove, disabledTools.
Remote server: url (req), type ("http", default inferred from url), headers, env, oauth.clientId, oauth.redirectUri ("host:port"), oauthScopes (top-level, NOT under oauth), disabled, autoApprove, disabledTools.
Transports¶
- stdio — default when
command+argspresent. - HTTP — when
urlpresent (ortype:"http"). Supports OAuth. No separate SSE type; HTTP covers SSE endpoints.
CLI setup¶
kiro-cli mcp add \
--name "awslabs.aws-documentation-mcp-server" \
--scope global \
--command "uvx" \
--args "awslabs.aws-documentation-mcp-server@latest" \
--env "FASTMCP_LOG_LEVEL=ERROR"
--scope global → ~/.kiro/settings/mcp.json. In-session inspection: /mcp.
Agent-level MCP override¶
includeMcpJson: false → agent uses only its own mcpServers, ignoring all mcp.json files. true → merges user+workspace mcp.json with the agent's own.
Tool name validation¶
- Must match
^[a-zA-Z][a-zA-Z0-9_]*$; ≤64 chars incl. server prefix. - Description must be non-empty.
- Violations → tool silently excluded (warning shown).
- Descriptions >10,000 chars → performance warning, still works.
Gotchas¶
disabledToolsremoves specific tools;disabled:truekills the whole server.- Two separate allow-lists: MCP
autoApprove(server-scoped MCP tools) vs agentallowedTools(agent-scoped built-ins). includeMcpJson:falsesilently drops allmcp.jsonservers.- Steering not auto-loaded in custom agents — declare in
resources. oauthScopesis top-level; placing it underoauthis silently ignored.- OAuth: only public/PKCE clients (no
client_secret) are supported. - Empty-scopes workaround:
"oauthScopes": []if scope errors occur. - Hyphenated MCP tool names (
get-file) fail validation and are excluded. mcp.jsonmerge is server-key-level; no within-entry field merge.--description/--mcp-serverflags exist only on the/agent createslash command, notkiro-cli agent create.type:"http"is explicit in agent-level examples but inferred fromurlin top-levelmcp.json. [INFERENCE]urlalone is sufficient there, not explicitly confirmed.
Sources¶
- https://kiro.dev/docs/cli/
- https://kiro.dev/docs/cli/mcp/
- https://kiro.dev/docs/cli/custom-agents/
- https://kiro.dev/docs/cli/custom-agents/creating/
- https://kiro.dev/docs/cli/hooks/
- https://kiro.dev/docs/cli/steering/
- https://kiro.dev/docs/cli/chat/
- https://kiro.dev/docs/cli/reference/slash-commands/
- https://kiro.dev/docs/mcp/
- https://kiro.dev/docs/mcp/configuration/