Server Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Server configuration in the Kiro system governs two primary areas: the Model Context Protocol (MCP) server and the contextual "Steering Documents" that guide the AI assistant's behavior. The MCP server configuration controls its operational state and tool approvals, while steering document configuration defines how and when project-specific guidelines are injected into the AI's context.
Proper configuration is essential for tailoring the Kiro IDE and AI assistant to specific project needs, standards, and workflows. This includes managing external tool interactions via MCP and ensuring the AI adheres to team conventions through steering documents. The system is designed to be flexible, with configurations stored in environment variables, JSON files, and Markdown front-matter.
Sources: spec-process-guide/resources/standards.md:81, kiro-web-app/src/pages/SystemDocs.tsx:30-38, 52-56
Model Context Protocol (MCP) Server
The MCP allows the Kiro AI to recommend and execute shell commands and other tools. Its behavior is managed through a mcp.json configuration file. The server is a WebSocket server that listens for tool execution requests.
Sources: mcp-server/src/kiro_mcp_server/server.py, kiro-web-app/src/pages/SystemDocs.tsx:52-54
MCP Configuration (mcp.json)
The server's behavior is defined by mcp.json. The system can use two mcp.json files for configuration. The server automatically reconnects when the configuration is changed.
Sources: kiro-web-app/src/pages/SystemDocs.tsx:58-60, 64-65
The table below details the available configuration options.
| Key | Type | Description | Example Value |
|---|---|---|---|
disabled | boolean | If true, completely disables the MCP server. | false |
autoApprove | Array | A list of MCP tool names that the user wants to be approved automatically. | ["shell", "fs"] |
Sources: mcp-server/examples/mcp-config.json:1-4, kiro-web-app/src/pages/SystemDocs.tsx:61-63
An example mcp-config.json file is shown below:
{
"disabled": false,
"autoApprove": ["shell", "fs"]
}
Sources: mcp-server/examples/mcp-config.json:1-4
Server Startup Logic
The Python-based MCP server reads the mcp.json configuration upon startup to determine its operational state.
The following diagram illustrates the server's startup and configuration loading process.
This diagram shows how the disabled flag in mcp.json acts as a kill switch for the server.
Sources: mcp-server/src/kiro_mcp_server/server.py:101-120, kiro-web-app/src/pages/SystemDocs.tsx:61-62
Steering Document Configuration
Steering documents are Markdown files located in the .kiro/steering/ directory of a workspace. They provide contextual guidelines, standards, and project-specific information to the AI assistant. Their inclusion in the AI's context is controlled by YAML front-matter within each file.
Sources: skills/create-steering-documents/SKILL.md:19-22, 116-122, kiro-web-app/src/pages/SystemDocs.tsx:30-33
Inclusion Mechanisms
There are three ways a steering document can be included in the AI's context, controlled by the inclusion key in the front-matter.
inclusion Value | Description |
|---|---|
always | Default behavior. The document is included in every interaction with the AI. No front-matter is needed for this. |
fileMatch | The document is included only when a file matching the fileMatchPattern glob is part of the active context. |
manual | The document is included only when explicitly referenced by the user in the chat (e.g., using a # trigger). |
Sources: skills/create-steering-documents/SKILL.md:24-28, 124-128, commands/create-steering-documents-standalone.md:196-202
Front-Matter Configuration
The front-matter is a YAML block at the top of the Markdown file.
| Key | Type | inclusion Mode | Description |
|---|---|---|---|
inclusion | string | All | Defines the inclusion mode (always, fileMatch, manual). |
fileMatchPattern | string | fileMatch | A glob pattern to match against file names in the context. |
Sources: skills/create-steering-documents/SKILL.md:124-128, commands/create-steering-documents-standalone.md:243-246
Examples
Conditional inclusion for frontend files:
---
inclusion: fileMatch
fileMatchPattern: '*.tsx|*.jsx|*.vue|*.svelte'
---
# Frontend Development Standards
...
Sources: skills/create-steering-documents/SKILL.md:68-71
Manual inclusion for API design guidelines:
---
inclusion: manual
---
# API Design Guidelines
...
Sources: skills/create-steering-documents/SKILL.md:91-93
Steering Document Inclusion Flow
The following diagram shows how the system decides which steering documents to include for a given AI interaction.
This sequence illustrates the multi-layered approach to building a rich, relevant context for the AI assistant.
Sources: skills/create-steering-documents/SKILL.md:24-28, commands/create-steering-documents-standalone.md:196-202, kiro-web-app/src/pages/SystemDocs.tsx:34-41
Summary
The Kiro system's configuration is split between operational settings for the MCP server and contextual guidance via steering documents. The mcp.json file provides a straightforward way to enable/disable the server and manage tool auto-approvals. The steering document system offers a powerful, flexible mechanism for injecting project-specific knowledge into the AI's workflow using a simple but effective front-matter configuration within Markdown files. Together, these systems allow developers to create a highly customized and context-aware AI development environment.