# Kiro CLI Chat — Configuration Reference

> Source: https://kiro.dev/docs/cli/chat/configuration/  
> Page updated: December 10, 2025

---

## Configuration File Paths

Kiro CLI configuration can be set at three scopes:

1. **Global** — applies across all projects: `~/.kiro/`
2. **Project** — specific to a project: `<project-root>/.kiro/`
3. **Agent** — defined in the agent config file: `<user-home | project-root>/.kiro/agents/`

| Configuration | Global Scope | Project Scope |
|---|---|---|
| MCP servers | `~/.kiro/settings/mcp.json` | `.kiro/settings/mcp.json` |
| Prompts | `~/.kiro/prompts` | `.kiro/prompts` |
| Custom agents | `~/.kiro/agents` | `.kiro/agents` |
| Steering | `~/.kiro/steering` | `.kiro/steering` |
| Settings | `~/.kiro/settings/cli.json` | *(N/A)* |

---

## What Can Be Configured at Each Scope

| Configuration | User Scope | Project Scope | Agent Scope |
|---|---|---|---|
| MCP servers | Yes | Yes | Yes |
| Prompts | Yes | Yes | No |
| Custom agents | Yes | Yes | N/A |
| Steering | Yes | Yes | Yes |
| Settings | Yes | N/A | N/A |

---

## Resolving Configuration Conflicts

Conflicts are resolved by selecting the configuration closest to where you are interacting with Kiro CLI.

- If MCP config exists in both global and project `mcp.json`, the project-level config wins when working in that project folder.
- If a custom agent is defined at both global and project scope, the agent-level configuration takes precedence.

Priority order:

| Configuration | Priority |
|---|---|
| MCP servers | Agent > Project > Global |
| Prompts | Project > Global |
| Custom agents | Project > Global |
| Steering | Project > Global |

> **Note:** MCP servers can be configured in three scopes and are handled differently due to the `includeMcpJson` agent setting. See [MCP server loading priority](https://kiro.dev/docs/cli/mcp/#mcp-server-loading-priority).