When a Kiro CLI Update Silently Breaks Your MCP Servers — The Approved Environment Variables Gotcha

🇯🇵 Original article (Japanese): Kiro CLI アップデートで MCP サーバーが突然動かなくなった話

Introduction

One morning, I ran my usual workflow with Kiro CLI and was greeted with a 401 Unauthorized error from my MCP server. Everything had been working fine the day before.

After investigation, I found that the Kiro CLI v2.4.0 update had changed how environment variables are expanded in MCP configuration files.

This article explains what changed and how to fix it.

TL;DR

• Kiro only expands ${VAR} references in MCP configs for variables registered in the Approved Environment Variables list
• Unregistered variables are passed as the literal string ${VAR} to the MCP server
• Fix: Add variable names to kiroAgent.mcpApprovedEnvVars in ~/.kiro/settings/cli.json

The Problem

Symptoms

MCP Server → 401 Unauthorized

My MCP configuration file used environment variable references:

{
  "mcpServers": {
    "my-service": {
      "command": "uvx",
      "args": ["mcp-my-service"],
      "env": {
        "SERVICE_URL": "https://service.example.com",
        "SERVICE_API_KEY": "${SERVICE_API_KEY}"
      }
    }
  }
}

Running echo $SERVICE_API_KEY in the shell returned the correct value, but the MCP server received the unexpanded string instead.

Root Cause: Approved Environment Variables

How It Works

Kiro includes a security feature called Approved Environment Variables. It prevents MCP servers from accessing arbitrary environment variables on your system.

From the official documentation:

For security, Kiro only expands environment variables that are explicitly approved. Only variables in the approved list will be expanded when found in MCP config files.

— Kiro Docs — MCP Best practices

Environment Variable Expansion Flow

Why It Suddenly Broke

Before v2.4.0, all environment variables were expanded (or the approval list defaults were more permissive), so everything worked without explicit registration. The update tightened the default behavior to "expand only approved variables."

How to Fix It

Configuration File Relationships

Step 1: Add Variables to the Approval List

Edit ~/.kiro/settings/cli.json and add the variable names you want to allow in kiroAgent.mcpApprovedEnvVars:

{
  "kiroAgent.mcpApprovedEnvVars": [
    "SERVICE_API_KEY",
    "GITHUB_TOKEN",
    "BRAVE_API_KEY"
  ]
}

You can also configure this from the command line:

kiro-cli settings kiroAgent.mcpApprovedEnvVars '["SERVICE_API_KEY"]'

Step 2: Use Environment Variable References in mcp.json

{
  "mcpServers": {
    "my-service": {
      "command": "uvx",
      "args": ["mcp-my-service"],
      "env": {
        "SERVICE_URL": "https://service.example.com",
        "SERVICE_API_KEY": "${SERVICE_API_KEY}"
      }
    }
  }
}

Step 3: Set Shell Environment Variables

# ~/.zshrc or ~/.bashrc
export SERVICE_API_KEY="your-api-key-here"

Step 4: Restart Kiro CLI and Verify

# Start a new session
kiro-cli chat

# Check MCP server status
/mcp

What NOT to Do

❌ Hardcode API Keys in mcp.json

{
  "env": {
    "SERVICE_API_KEY": "f2c77124e8761272096e10a962a3874d42020d9c"
  }
}

The official documentation explicitly discourages this:

Never commit configuration files with sensitive tokens to version control

— Kiro Docs — MCP Best practices

If you must hardcode values:

• Restrict permissions with chmod 600 .kiro/settings/mcp.json
• Add the file to .gitignore to exclude it from version control

Best Practices

MCP Configuration File Precedence

When multiple configuration files exist, they are loaded in the following order of precedence:

When the same server is defined at multiple levels, the higher-priority config completely overrides the lower one (no merging).

Conclusion

1. Since Kiro CLI v2.4.0, environment variable expansion in MCP configs is governed by an approval list
2. You must register variable names in kiroAgent.mcpApprovedEnvVars in cli.json
3. Best practice: Pass API keys via environment variables and use only ${VAR} references in mcp.json

If your MCP servers suddenly start returning authentication errors, check the approval list first.

References

• Kiro Docs — MCP Best practices (IDE) — Official explanation of Approved Environment Variables
• Kiro Docs — CLI > MCP > Configuration — MCP config file structure and environment variables
• Kiro Docs — CLI > MCP > Security — CLI security best practices
• Kiro Docs — CLI > Reference > Settings — cli.json settings reference
• Kiro Changelog — CLI v2.4.0 — v2.4.0 release notes