DEV Community

Akira Tateishi
Akira Tateishi

Posted on

When a Kiro CLI Update Silently Breaks Your MCP Servers β€” The Approved Environment Variables Gotcha

#kiro #mcp #cli

πŸ‡―πŸ‡΅ 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
Enter fullscreen mode Exit fullscreen mode

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}"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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

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

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"
  ]
}
Enter fullscreen mode Exit fullscreen mode

You can also configure this from the command line:

kiro-cli settings kiroAgent.mcpApprovedEnvVars '["SERVICE_API_KEY"]'
Enter fullscreen mode Exit fullscreen mode

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}"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Step 3: Set Shell Environment Variables 

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

Step 4: Restart Kiro CLI and Verify 

# Start a new session
kiro-cli chat

# Check MCP server status
/mcp
Enter fullscreen mode Exit fullscreen mode

What NOT to Do

❌ Hardcode API Keys in mcp.json 

{
  "env": {
    "SERVICE_API_KEY": "f2c77124e8761272096e10a962a3874d42020d9c"
  }
}
Enter fullscreen mode Exit fullscreen mode

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

Best Practices

Aspect Recommended Not Recommended
API key storage Shell environment variables Hardcoded in mcp.json
mcp.json in git βœ… Safe (no secrets) ❌ Leak risk
Key rotation Just update the env var Rewrite all mcp.json files
Sharing across projects Env vars are shared Copy per project

MCP Configuration File Precedence

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

MCP Configuration File 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

Top comments (0)