***

title: Integrate Unleash with Kiro
'og:site\_name': Unleash Documentation
'og:title': Integrate Unleash with Kiro for AI-powered feature flag management
description: >-
Configure the Unleash MCP server to automate feature flag management in Kiro
IDE and CLI.
keywords: >-
kiro, mcp, model context protocol, ai, llm, coding assistants, feature flags,
automation
max-toc-depth: 3
slug: integrate/kiro
--------------------

The [Unleash MCP server](/integrate/mcp) connects Kiro to your Unleash instance, enabling AI-assisted feature flag management.
You can evaluate code changes, create flags, generate wrapping code, manage rollouts, and clean up flags from within Kiro's spec-driven development workflow.

Kiro supports MCP across two interfaces:

* **Kiro IDE** — The primary interface, built on Code OSS with specs, steering files, hooks, and Powers
* **Kiro CLI** — Interactive terminal-based chat (successor to Amazon Q Developer CLI)

Kiro's structured primitives create a natural pipeline for feature flags: specs surface risk at the requirements stage, steering files encode your team's conventions, hooks automate evaluation on file events, and Powers bundle everything into a shareable package.

## Prerequisites

Before you begin, make sure you have the following:

* Node.js 18 or later: The MCP server is distributed as an npm package
* Kiro: [IDE or CLI](https://kiro.dev/) installed
* An Unleash instance: Cloud or self-hosted, with API access enabled
* A [personal access token](https://docs.getunleash.io/concepts/api-tokens-and-client-keys#personal-access-tokens) (PAT): With permissions to create and manage feature flags

## Install the MCP server

The Unleash MCP server runs as a local stdio process. Configuration differs between the IDE and CLI, but both use the same npm package and credentials.

Kiro uses `${VAR}` expansion for environment variables. Create a credentials file and source it from your shell profile:

<Steps>
  <Step title="Create credentials file">
    ```bash
    mkdir -p ~/.unleash
    cat > ~/.unleash/mcp.env << 'EOF'
    UNLEASH_BASE_URL=https://your-instance.getunleash.io/api
    UNLEASH_PAT=your-personal-access-token
    UNLEASH_DEFAULT_PROJECT=default
    EOF
    chmod 600 ~/.unleash/mcp.env
    ```
  </Step>

  <Step title="Source in shell profile">
    Add to your `~/.zshrc` or `~/.bashrc`:

    ```bash
    if [ -f ~/.unleash/mcp.env ]; then
      source ~/.unleash/mcp.env
      export UNLEASH_BASE_URL UNLEASH_PAT UNLEASH_DEFAULT_PROJECT
    fi
    ```
  </Step>

  <Step title="Reload your shell">
    ```bash
    source ~/.zshrc  # or ~/.bashrc
    ```
  </Step>
</Steps>

| Variable                  | Description                                                                                          | Required |
| ------------------------- | ---------------------------------------------------------------------------------------------------- | -------- |
| `UNLEASH_BASE_URL`        | Your Unleash instance API URL. Include `/api` at the end.                                            | Yes      |
| `UNLEASH_PAT`             | A personal access token with flag creation permissions.                                              | Yes      |
| `UNLEASH_DEFAULT_PROJECT` | The default project for flag operations. If omitted, you must specify `projectId` in each tool call. | No       |

Now configure your preferred interface:

<Tabs>
  <Tab title="Kiro IDE">
    **Requirements:** [Kiro IDE](https://kiro.dev) installed.

    **Enable MCP support (one-time step):**

    MCP is disabled by default. Before configuring any MCP servers, enable it:

    1. Open Settings (`Cmd+,` on macOS, `Ctrl+,` on Windows/Linux)
    2. Search for **MCP**
    3. Enable the **Kiro: MCP** setting

    <Warning>
      Without this setting enabled, MCP servers will not connect and tools will not appear. This only needs to be done once.
    </Warning>

    You can add the Unleash MCP server using the Command Palette or by creating the configuration file manually.

    <Tabs>
      <Tab title="Command Palette">
        <Steps>
          <Step title="Open the MCP configuration">
            Open the Command Palette (`Cmd+Shift+P` on macOS, `Ctrl+Shift+P` on Windows/Linux) and run **Kiro: Open workspace MCP config (JSON)**.

            This opens `.kiro/settings/mcp.json` in your workspace.

            For user-scoped (global) configuration, run **Kiro: Open user MCP config (JSON)** instead. This opens `~/.kiro/settings/mcp.json`.
          </Step>

          <Step title="Add the Unleash server">
            Paste the following configuration:

            ```json title=".kiro/settings/mcp.json"
            {
              "mcpServers": {
                "unleash": {
                  "command": "npx",
                  "args": ["-y", "@unleash/mcp@latest", "--log-level", "error"],
                  "env": {
                    "UNLEASH_BASE_URL": "${UNLEASH_BASE_URL}",
                    "UNLEASH_PAT": "${UNLEASH_PAT}",
                    "UNLEASH_DEFAULT_PROJECT": "${UNLEASH_DEFAULT_PROJECT}"
                  }
                }
              }
            }
            ```

            When you save this file, Kiro displays a popup listing unapproved environment variables.
            Click **Allow** to approve `UNLEASH_BASE_URL`, `UNLEASH_PAT`, and `UNLEASH_DEFAULT_PROJECT`.
            You can also manage approved variables later in Settings under **Mcp Approved Env Vars**.
          </Step>

          <Step title="Save and verify">
            Open the **MCP Servers** tab in the Kiro panel to confirm the Unleash server appears with its tools listed.

            To view MCP logs, right-click the Unleash server in the MCP Servers tab and select **Show MCP Logs**.
            You can also open the **Output** panel and choose **Kiro - MCP Logs** from the dropdown.
          </Step>
        </Steps>
      </Tab>

      <Tab title="Create file manually">
        <Steps>
          <Step title="Create the configuration file">
            Create `.kiro/settings/mcp.json` at your project root:

            ```json title=".kiro/settings/mcp.json"
            {
              "mcpServers": {
                "unleash": {
                  "command": "npx",
                  "args": ["-y", "@unleash/mcp@latest", "--log-level", "error"],
                  "env": {
                    "UNLEASH_BASE_URL": "${UNLEASH_BASE_URL}",
                    "UNLEASH_PAT": "${UNLEASH_PAT}",
                    "UNLEASH_DEFAULT_PROJECT": "${UNLEASH_DEFAULT_PROJECT}"
                  }
                }
              }
            }
            ```

            The file contains no credentials, only variable references that expand at runtime.
            You can safely commit it to version control.

            When you save this file, Kiro displays a popup listing unapproved environment variables.
            Click **Allow** to approve `UNLEASH_BASE_URL`, `UNLEASH_PAT`, and `UNLEASH_DEFAULT_PROJECT`.
            You can also manage approved variables later in Settings under **Mcp Approved Env Vars**.
          </Step>

          <Step title="Restart Kiro">
            Restart the IDE or reload the window so Kiro picks up the new configuration.
          </Step>

          <Step title="Verify the installation">
            Open the **MCP Servers** tab in the Kiro panel. The Unleash server should appear with its tools listed.

            Within a Kiro chat session, ask: "What Unleash MCP tools are available?" Kiro lists all nine tools.
          </Step>
        </Steps>
      </Tab>
    </Tabs>

    ### Configure`autoApprove` and `disabledTools`\*\*

    Kiro supports two MCP configuration properties for controlling tool approval:

    | Property        | Type             | Description                                                                               |
    | --------------- | ---------------- | ----------------------------------------------------------------------------------------- |
    | `autoApprove`   | Array of strings | Tool names that Kiro can invoke without asking for confirmation. Use `"*"` for all tools. |
    | `disabledTools` | Array of strings | Tool names to hide from the agent entirely.                                               |

    Example with auto-approval for read-only tools:

    ```json title=".kiro/settings/mcp.json" {11-12}
    {
      "mcpServers": {
        "unleash": {
          "command": "npx",
          "args": ["-y", "@unleash/mcp@latest", "--log-level", "error"],
          "env": {
            "UNLEASH_BASE_URL": "${UNLEASH_BASE_URL}",
            "UNLEASH_PAT": "${UNLEASH_PAT}",
            "UNLEASH_DEFAULT_PROJECT": "${UNLEASH_DEFAULT_PROJECT}"
          },
          "autoApprove": ["get_flag_state", "detect_flag", "evaluate_change"],
          "disabledTools": []
        }
      }
    }
    ```

    <Tip>
      Use `autoApprove` for read-only tools like `get_flag_state`, `detect_flag`, and `evaluate_change`.
      Keep write operations like `create_flag` and `toggle_flag_environment` behind manual approval for safety.
    </Tip>

    **Configuration scopes:**

    | Location                            | Scope     | Use case                              |
    | ----------------------------------- | --------- | ------------------------------------- |
    | `.kiro/settings/mcp.json` (project) | Workspace | Team-shared, version controlled       |
    | `~/.kiro/settings/mcp.json`         | User      | Personal settings across all projects |

    Both are merged; workspace takes precedence on conflict. For team collaboration, use the workspace-level file.
  </Tab>

  <Tab title="Kiro CLI">
    **Requirements:** macOS, Linux, or WSL.

    The Kiro CLI replaced the Amazon Q Developer CLI in November 2025.
    If you previously used the Q CLI, your MCP configuration, steering files, and subscriptions migrate automatically.
    For details, see [Upgrading from Amazon Q Developer CLI](https://kiro.dev/docs/cli/migrating-from-q/).

    <Steps>
      <Step title="Install the Kiro CLI">
        ```bash
        curl -fsSL https://cli.kiro.dev/install | bash
        ```
      </Step>

      <Step title="Verify the installation">
        ```bash
        kiro-cli --version
        ```
      </Step>

      <Step title="Confirm MCP configuration">
        The CLI shares the same `.kiro/settings/mcp.json` and `.kiro/steering/` files as the IDE.
        If you already configured the MCP server for the Kiro IDE, the CLI picks it up automatically.

        If you haven't configured it yet, create the `.kiro/settings/mcp.json` file as shown in the Kiro IDE tab.
      </Step>
    </Steps>

    Run `kiro-cli` to start an interactive chat session.
    You can use the same Unleash MCP tools as in the IDE: evaluate changes, create flags, check flag state, and run cleanup workflows.
  </Tab>
</Tabs>

## Tool reference

The Unleash MCP server exposes nine tools. The following table summarizes each tool and when to use it.

<StickyTable>
  | Tool                      | Description                                                                       | When to use                       |
  | ------------------------- | --------------------------------------------------------------------------------- | --------------------------------- |
  | `evaluate_change`         | Analyzes a code change and determines whether it should be behind a feature flag. | Before implementing risky changes |
  | `detect_flag`             | Searches for existing flags that match a description to prevent duplicates.       | Before creating new flags         |
  | `create_flag`             | Creates a new feature flag with proper naming, typing, and metadata.              | When no suitable flag exists      |
  | `wrap_change`             | Generates framework-specific code to guard a feature behind a flag.               | After creating a flag             |
  | `get_flag_state`          | Returns the current state, strategies, and metadata for a flag.                   | Debugging, status checks          |
  | `set_flag_rollout`        | Configures rollout percentages and activation strategies.                         | Gradual releases                  |
  | `toggle_flag_environment` | Enables or disables a flag in a specific environment.                             | Testing, staged rollouts          |
  | `remove_flag_strategy`    | Deletes a rollout strategy from a flag.                                           | Simplifying flag configuration    |
  | `cleanup_flag`            | Returns file locations and instructions for removing a flag after rollout.        | After full rollout                |
</StickyTable>

## Workflows

This section describes common workflows for using the Unleash MCP server with Kiro.

### Evaluate and wrap a risky change

Use this workflow when implementing a change that might affect production stability, such as a payment integration, authentication flow, or external API call.

<Steps>
  <Step title="Evaluate the change">
    Tell Kiro what you are working on:

    ```text
    Evaluate whether the Stripe payment integration should be behind a feature flag.
    The change modifies the checkout service and handles credit card processing.
    ```

    Kiro calls `evaluate_change` and returns a recommendation with a suggested flag name.
  </Step>

  <Step title="Check for duplicates">
    Kiro automatically calls `detect_flag` to search for existing flags.
    If a suitable flag exists, Kiro suggests reusing it instead of creating a duplicate.
  </Step>

  <Step title="Create the flag">
    If no suitable flag exists:

    ```text
    Create a release flag for the Stripe payment integration.
    ```

    Kiro calls `create_flag` with the appropriate name, type, and description.
    The flag is created in Unleash, disabled by default.
  </Step>

  <Step title="Wrap the code">
    Generate framework-specific guard code:

    ```text
    Wrap the Stripe checkout handler with the stripe-payment-integration flag.
    This is a Node.js Express application.
    ```

    Kiro calls `wrap_change` and returns code like this:

    ```javascript title="checkout.js"
    const { isEnabled } = require('unleash-client');

    app.post('/checkout', async (req, res) => {
      const context = { userId: req.user.id };

      if (isEnabled('stripe-payment-integration', context)) {
        // New Stripe payment flow
        const result = await stripeService.processPayment(req.body);
        return res.json(result);
      } else {
        // Existing payment flow
        const result = await legacyPaymentService.process(req.body);
        return res.json(result);
      }
    });
    ```
  </Step>
</Steps>

### Spec-driven flag creation

Use this workflow when a Kiro spec identifies a high-risk task during the design phase.
Instead of flagging code after implementation, the spec surfaces risk before a single line is written.

<Steps>
  <Step title="Create a spec">
    Create a spec for your feature (for example, "Integrate Stripe payment processing").
    During the Design phase, Kiro identifies the payment integration as high-risk based on the architectural analysis.
  </Step>

  <Step title="Steering files trigger evaluation">
    When Kiro begins implementing the payment task, a steering file targeting `src/payments/**` instructs it to evaluate risk:

    ```text
    Implement the payment integration task from the checkout spec.
    Evaluate whether it needs a feature flag.
    ```

    Kiro calls `evaluate_change` with the task description and context from the spec.
  </Step>

  <Step title="Create and wrap in one flow">
    If a flag is needed, Kiro calls `detect_flag`, `create_flag`, and `wrap_change` as part of the same task implementation.
    The flag is in place before the task is marked complete.
  </Step>
</Steps>

<Tip>
  Spec-driven flag creation catches risk at the requirements stage rather than during code review. The flag becomes part of the implementation plan, not an afterthought.
</Tip>

### Manage rollouts across environments

Use this workflow to enable a flag in staging for testing while keeping it disabled in production.

<Tabs>
  <Tab title="Check flag state">
    ```text
    What is the current state and rollout strategies for stripe-payment-integration?
    ```

    Kiro calls `get_flag_state` and returns the flag metadata, enabled environments, and active strategies.
  </Tab>

  <Tab title="Enable in staging">
    ```text
    Enable stripe-payment-integration in the staging environment.
    ```

    Kiro calls `toggle_flag_environment` to enable the flag in staging while keeping it disabled in production.
  </Tab>
</Tabs>

### Clean up after rollout

Use this workflow when a feature has been fully rolled out and the flag is no longer needed.

```text
Clean up the stripe-payment-integration flag. The feature is fully rolled out.
```

Kiro calls `cleanup_flag` and returns:

* All files and line numbers where the flag is used
* Which code path to preserve (the "enabled" branch)
* Suggestions for tests to run after removal

Review the list, remove the conditional branches, and delete the flag from Unleash.

<Tip>
  Feature flags should be temporary. Regularly clean up flags after successful rollouts to prevent [technical debt](/concepts/technical-debt).
</Tip>

## Steering file templates

Steering files encode your team's [FeatureOps](https://featureops.io/) policies, so Kiro considers feature flags automatically.
Store them in `.kiro/steering/` and choose the inclusion mode that matches the policy's scope.

For more details on steering files, see the [Kiro steering file documentation](https://kiro.dev/docs/steering/).

### Always-included: universal conventions

This file loads into every Kiro interaction. Use it for organization-wide flag standards.

```markdown title=".kiro/steering/feature-flags.md"
---
inclusion: always
---

# Feature Flag Conventions

When making changes to this codebase, follow these feature flag practices:

1. **Always evaluate risk**: Before implementing high-risk changes (payments,
   authentication, data migrations, external integrations), use the Unleash MCP
   server to evaluate whether a feature flag is needed.

2. **Naming conventions**: Use the format `{domain}-{feature}-{variant}`.
   Examples: `checkout-stripe-integration`, `auth-sso-google`, `api-rate-limiting`.

3. **Flag types**:
   - `release`: For gradual feature rollouts
   - `experiment`: For A/B tests and experiments
   - `operational`: For system behavior toggles
   - `kill-switch`: For emergency shutdowns
   - `permission`: For role-based access

4. **Prefer reuse**: Before creating a new flag, check if a similar flag already
   exists using the detect_flag tool.

5. **Clean up after rollout**: Once a feature is fully released (100% rollout for
   2+ weeks), use cleanup_flag to remove dead code.

## Unleash MCP Server

This project uses the Unleash MCP server for feature flag management. Configuration
is in `.kiro/settings/mcp.json`. Credentials are sourced from environment variables.

Available tools: evaluate_change, detect_flag, create_flag, wrap_change,
get_flag_state, set_flag_rollout, toggle_flag_environment, remove_flag_strategy,
cleanup_flag.
```

### fileMatch: domain-specific policies

This file loads only when the conversation involves files matching the glob pattern.
Use it for high-risk domains that always require flags.

```markdown title=".kiro/steering/payments-flags.md"
---
inclusion: fileMatch
fileMatchPattern: ["src/payments/**/*.ts", "src/payments/**/*.tsx"]
---

# Payments Domain — Feature Flag Policy

All changes in the payments domain require feature flags. No exceptions.

- Use `kill-switch` type for external payment provider integrations
  (Stripe, PayPal, etc.)
- Use `release` type for internal payment logic changes
- Naming: `payments-{feature}-{variant}`
  (e.g., `payments-stripe-checkout`, `payments-refund-v2`)
- Always include a fallback path for external provider calls
- Evaluate risk with evaluate_change before writing implementation code
```

### Auto-included: rollout guidance

This file loads automatically when Kiro detects the conversation is about rollout strategies.

```markdown title=".kiro/steering/rollout-guidance.md"
---
inclusion: auto
name: rollout-guidance
description: Guidance for configuring feature flag rollout strategies. Use when
  setting up rollouts, configuring milestones, or discussing gradual releases.
---

# Rollout Strategy Defaults

When setting up rollouts with set_flag_rollout, use these defaults unless
specified otherwise:

- Start at 10% rollout
- Wait 24 hours before advancing
- Pause if error rate exceeds 1% or p95 latency increases by more than 20%

## Standard milestones

| Milestone | Percentage | Hold period | Advance condition |
|-----------|-----------|-------------|-------------------|
| Canary | 10% | 24 hours | Error rate < 1%, latency stable |
| Beta | 50% | 48 hours | Error rate < 0.5%, no regressions |
| GA | 100% | — | All metrics healthy for 48 hours |

## Cleanup cadence

Run cleanup_flag weekly for flags that have been at 100% for more than 14 days.
```

## Hook examples

Hooks automate feature flag evaluation based on IDE events.
Store them as `.kiro.hook` files in `.kiro/hooks/`.

For more details on hooks, see the [Kiro hooks documentation](https://kiro.dev/docs/hooks/).

### Evaluate on file save

This hook fires whenever a file in the payments domain is saved.
Kiro automatically evaluates whether the change needs a flag.

```json title=".kiro/hooks/evaluate-payments-flag.kiro.hook"
{
  "enabled": true,
  "name": "Evaluate payments changes for feature flags",
  "description": "Automatically evaluates whether saved changes in the payments domain should be behind a feature flag",
  "version": "1",
  "when": {
    "type": "fileSave",
    "filePattern": "src/payments/**/*.ts"
  },
  "then": {
    "type": "askAgent",
    "prompt": "The file $FILE_PATH was just saved with changes in the payments domain. Use the Unleash MCP server's evaluate_change tool to determine if these changes should be behind a feature flag. If yes, suggest a flag name following our payments naming convention (payments-{feature}-{variant}) and offer to create it."
  }
}
```

### Manual trigger for flag audit

This hook runs on demand when triggered by the user.
It audits all flags in the project and generates a cleanup report.

```json title=".kiro/hooks/flag-audit.kiro.hook"
{
  "enabled": true,
  "name": "Feature flag audit",
  "description": "Run an audit of all feature flags, identifying stale flags and cleanup opportunities",
  "version": "1",
  "when": {
    "type": "userTriggered"
  },
  "then": {
    "type": "askAgent",
    "prompt": "Run a comprehensive feature flag audit using the Unleash MCP server. For each flag in the default project: 1) Use get_flag_state to check its current state, 2) Identify flags at 100% rollout for more than 14 days, 3) Identify flags that haven't been modified in 90 days, 4) Generate a prioritized cleanup report with recommendations for each stale flag."
  }
}
```

<Info>
  Adjust the `filePattern` in the File Save hook to match your project's high-risk directories.
  You can create multiple hooks targeting different domains (e.g., `src/auth/**`, `src/api/**`).
</Info>

## Unleash Power

A [Power](https://kiro.dev/docs/powers/) bundles MCP tools, steering files, and hook definitions into a single installable package.
The Unleash Power is the recommended way to distribute the integration across teams and projects.

### Directory structure

```
power-unleash/
├── POWER.md
├── mcp.json
└── steering/
    ├── feature-flag-conventions.md
    ├── rollout-guidance.md
    └── cleanup-cadence.md
```

### POWER.md

The `POWER.md` file defines activation keywords and onboarding instructions.
When a developer mentions "feature flag," "rollout," or "unleash" in chat, Kiro loads the Power's tools and steering files into context.

```markdown title="power-unleash/POWER.md"
---
name: "unleash"
displayName: "Unleash Feature Flags"
description: "Automate feature flag management with Unleash. Evaluate code changes for risk, create flags with consistent naming, generate SDK wrapping code, manage rollouts, and clean up stale flags."
keywords: ["feature flag", "feature toggle", "rollout", "unleash", "release", "experiment", "kill-switch", "canary", "progressive delivery", "featureops"]
---

# Onboarding

## Step 1: Verify prerequisites

- **Node.js 18+**: Verify with `node --version`
- **Unleash instance**: Cloud or self-hosted, with API access
- **Personal Access Token**: With permissions to create and manage flags

## Step 2: Set environment variables

Create a credentials file and source it from your shell profile:

\`\`\`bash
mkdir -p ~/.unleash
cat > ~/.unleash/mcp.env << 'EOF'
UNLEASH_BASE_URL=https://your-instance.getunleash.io/api
UNLEASH_PAT=your-personal-access-token
UNLEASH_DEFAULT_PROJECT=default
EOF
chmod 600 ~/.unleash/mcp.env
\`\`\`

Add to `~/.zshrc` or `~/.bashrc`:

\`\`\`bash
if [ -f ~/.unleash/mcp.env ]; then
  source ~/.unleash/mcp.env
  export UNLEASH_BASE_URL UNLEASH_PAT UNLEASH_DEFAULT_PROJECT
fi
\`\`\`

## Step 3: Add hooks (optional)

Save a File Save hook to `.kiro/hooks/evaluate-payments-flag.kiro.hook`
to automatically evaluate payments changes. Adjust the `filePattern` to
match your project's high-risk directories.

# When to Load Steering Files

- Setting up feature flags → `feature-flag-conventions.md`
- Configuring rollout strategies → `rollout-guidance.md`
- Cleaning up stale flags → `cleanup-cadence.md`
```

### mcp.json

```json title="power-unleash/mcp.json"
{
  "mcpServers": {
    "unleash": {
      "command": "npx",
      "args": ["-y", "@unleash/mcp@latest", "--log-level", "error"],
      "env": {
        "UNLEASH_BASE_URL": "${UNLEASH_BASE_URL}",
        "UNLEASH_PAT": "${UNLEASH_PAT}",
        "UNLEASH_DEFAULT_PROJECT": "${UNLEASH_DEFAULT_PROJECT}"
      },
      "autoApprove": ["get_flag_state", "detect_flag", "evaluate_change"]
    }
  }
}
```

### Steering files

<Accordion title="steering/feature-flag-conventions.md">
  ```markdown
  # Feature Flag Conventions

  ## Naming
  Use the format `{domain}-{feature}-{variant}`.
  Examples: `checkout-stripe-integration`, `auth-sso-google`.

  ## Flag types
  - `release` – Gradual feature rollouts
  - `experiment` – A/B tests
  - `operational` – System behavior toggles
  - `kill-switch` – Emergency shutdowns
  - `permission` – Role-based access

  ## Rules
  - Always use detect_flag before creating a new flag
  - Evaluate risk with evaluate_change for changes in payments, auth,
    data migrations and external integrations
  - Use kill-switch type for any external dependency integration
  ```
</Accordion>

<Accordion title="steering/rollout-guidance.md">
  ```markdown
  # Rollout Strategy Defaults

  - Start at 10% rollout
  - Hold 24 hours before advancing
  - Pause if error rate > 1% or p95 latency increases > 20%
  - Standard milestones: 10% → 50% → 100%
  - Each milestone requires 24-48 hours of healthy metrics
  ```
</Accordion>

<Accordion title="steering/cleanup-cadence.md">
  ```markdown
  # Flag Cleanup Cadence

  - Flags at 100% rollout for more than 14 days should be cleaned up
  - Run cleanup_flag to get file locations and removal instructions
  - Preserve the "enabled" code path; remove the conditional and fallback
  - Run tests after removing flag code to catch regressions
  - Delete the flag from Unleash after code cleanup is merged
  ```
</Accordion>

### Install the Power

You can install the Unleash Power from a local path or from GitHub:

* **From local path:** Open the Powers panel, select "Add power from Local Path," and choose the `power-unleash/` directory.
* **From GitHub:** Open the Powers panel, select "Add power from GitHub," and enter the repository URL.

When installed, the Power's MCP server is auto-registered in `~/.kiro/settings/mcp.json` under the "Powers" section with a namespaced server name (e.g., `power-unleash-unleash`).

For more details on creating and distributing Powers, see the [Kiro Powers documentation](https://kiro.dev/docs/powers/).

## Prompt patterns

The following prompt patterns help you use the MCP tools effectively.

<Accordion title="Evaluate and create a flag">
  **Intent:** Determine if a change requires a feature flag, then create and wrap it.

  **Prompt:**

  ```text
  Evaluate whether the [description of change] should be behind a feature flag.
  The change modifies [component/service].
  ```

  **Expected behavior:** Kiro calls `evaluate_change`, then `detect_flag`, `create_flag`, and `wrap_change` as needed.
</Accordion>

<Accordion title="Detect and reuse existing flags">
  **Intent:** Avoid duplicate flags when similar functionality exists.

  **Prompt:**

  ```text
  Before creating a new flag for [feature], check if a similar flag already exists
  and suggest reusing it if appropriate.
  ```

  **Expected behavior:** Kiro calls `detect_flag` and presents matches with confidence levels.
</Accordion>

<Accordion title="Toggle or check flag state">
  **Intent:** Enable, disable, or query a flag in a specific environment.

  **Prompts:**

  ```text
  Enable [flagName] in the staging environment.
  ```

  ```text
  What is the current state and rollout strategies for [flagName]?
  ```

  **Expected behavior:** Kiro calls `toggle_flag_environment` or `get_flag_state`.
</Accordion>

<Accordion title="Clean up a flag">
  **Intent:** Safely remove flagged code and delete unused flags.

  **Prompts:**

  ```text
  Clean up the [flagName] flag now that the feature has fully shipped.
  ```

  ```text
  Clean up the [flagName] flag after the A/B testing experiment, only keep [variant].
  ```

  **Expected behavior:** Kiro calls `cleanup_flag` and provides removal instructions.
</Accordion>

<Accordion title="Spec-triggered flag evaluation">
  **Intent:** Evaluate flag requirements as part of spec-driven task implementation.

  **Prompt:**

  ```text
  Implement the payment integration task from the checkout spec.
  Evaluate whether it needs a feature flag.
  ```

  **Expected behavior:** Kiro reads the spec tasks, identifies high-risk ones based on steering file rules, and calls `evaluate_change` for each. Flags are created and wrapping code is generated as part of the task implementation.
</Accordion>

<Accordion title="Hook-triggered automatic evaluation">
  **Intent:** Automatically evaluate code changes when files are saved.

  **Trigger:** A File Save hook fires when source files in a target directory are saved.

  **Expected behavior:** The hook sends an agent prompt that calls `evaluate_change` with the saved file's context. If a flag is needed, Kiro notifies you and offers to create it. In Supervised mode, you approve each step. In Autopilot mode, the flag is created automatically.
</Accordion>

## Enterprise governance

Kiro provides enterprise controls through AWS IAM Identity Center (which can federate to external identity providers such as Okta and Microsoft Entra ID).

* **Extension registry governance** — Point the IDE at a curated extension registry to control which extensions are available
* **Web tools toggle** — Enable or disable web search and fetch per organization policy
* **Supervised mode enforcement** — Require supervised mode for all users, preventing autonomous agent actions
* **Trusted commands list** — Define which shell commands the agent can execute

For MCP server governance, commit `.kiro/settings/mcp.json` to version control. This ensures all team members use the same MCP servers with the same settings.

<Tip>
  Use Supervised mode for high-risk flag operations (creation, rollout configuration, cleanup).
  Autopilot mode works well for read-only operations like checking flag state and evaluating changes.
</Tip>

## Troubleshooting

<Accordion title="MCP server not appearing in Kiro">
  * Check `.kiro/settings/mcp.json` for syntax errors
  * Verify the file is in the correct location (workspace root under `.kiro/settings/`)
  * Restart Kiro after making changes
  * Right-click the server in the MCP Servers tab and select **Show MCP Logs**
</Accordion>

<Accordion title="Unapproved environment variables">
  If you see "Found unapproved environment variables in MCP config," Kiro requires explicit approval before expanding variables.

  * When you first save the config, click **Allow** on the popup to approve the listed variables
  * Or open Settings, search for **Mcp Approved Env Vars**, and add `UNLEASH_BASE_URL`, `UNLEASH_PAT`, and `UNLEASH_DEFAULT_PROJECT`
  * After approving, restart Kiro or reload the window
</Accordion>

<Accordion title="Environment variables not expanding">
  * Restart your terminal or IDE after modifying your shell profile
  * Run `source ~/.zshrc` to reload
  * Kiro inherits environment variables from the shell that launched it
  * Verify variables are exported: `echo $UNLEASH_BASE_URL`
  * Verify the variables are approved in Settings → **Mcp Approved Env Vars**
</Accordion>

<Accordion title="Authentication failed">
  * Confirm your Unleash PAT is valid and has not expired
  * Check that the PAT has permissions to create and manage feature flags
  * Verify that `UNLEASH_BASE_URL` includes `/api` at the end
  * Test directly: `curl -H "Authorization: $UNLEASH_PAT" "$UNLEASH_BASE_URL/admin/projects"`
</Accordion>

<Accordion title="Hook not firing">
  * Verify the hook file is in `.kiro/hooks/` and has the `.kiro.hook` extension
  * Check that `enabled` is `true` in the hook JSON
  * Verify the `filePattern` matches the saved file's path
  * For hooks documentation, see [Kiro hook types](https://kiro.dev/docs/hooks/types)
</Accordion>

<Accordion title="Power not activating">
  * Check that keywords in the `POWER.md` frontmatter match what you are saying in chat
  * Powers activate on keyword matches — use terms like "feature flag," "rollout," or "unleash"
  * Verify the Power is installed in the Powers panel
</Accordion>

<Accordion title="autoApprove not working">
  * The `autoApprove` array must use exact tool names
  * Use `"*"` to approve all tools, or list specific names like `["get_flag_state", "detect_flag"]`
  * Verify the property is inside the server configuration object, not at the root level
</Accordion>

<Accordion title="Workspace vs user config conflict">
  Workspace configuration (`.kiro/settings/mcp.json`) takes precedence over user configuration (`~/.kiro/settings/mcp.json`). If a server is disabled in workspace config, it remains disabled even if enabled in user config.
</Accordion>

## Best practices

Follow these guidelines for effective feature flag management with Kiro.

<CardGroup cols={2}>
  <Card title="Keep humans in the loop" icon="user-check">
    While the MCP server can automate flag creation, high-risk changes should involve human review. Use Supervised mode for flag creation, rollout plans, and cleanup decisions.
  </Card>

  <Card title="Define naming conventions" icon="tag">
    Establish organization-wide standards for flag names (e.g., `domain-feature-variant`) and types. Encode these in steering files so Kiro applies them automatically.
  </Card>

  <Card title="Prevent duplication" icon="copy-slash">
    Always use `detect_flag` before creating new flags. This keeps naming consistent and reduces fragmentation across services.
  </Card>

  <Card title="Keep flags temporary" icon="clock">
    Feature flags should be removed after successful rollouts. Use `cleanup_flag` regularly to prevent technical debt. Set up a Manual Trigger hook for periodic audits.
  </Card>

  <Card title="Use workspace scope for teams" icon="users">
    Configure MCP servers at workspace scope (`.kiro/settings/mcp.json`) and commit to version control. All team members get the same configuration.
  </Card>

  <Card title="Encode policies in steering files" icon="file-code">
    Write your feature flag guidelines in steering files with appropriate inclusion modes. Kiro reads these files and applies the guidance automatically based on context.
  </Card>
</CardGroup>

## Related resources

* [Unleash MCP server on GitHub](https://github.com/Unleash/unleash-mcp)
* [Spec-Driven Feature Flags: How Kiro and Unleash Turn Requirements into Safe Releases](https://www.getunleash.io/blog/spec-driven-feature-flags-kiro)
* [Kiro documentation](https://kiro.dev/docs/)
* [Kiro MCP configuration](https://kiro.dev/docs/mcp/)
* [Impact Metrics](/concepts/impact-metrics)
* [Unleash architecture overview](/get-started/unleash-overview)