Kiro IDE の mcp.json で 環境変数が反映されないときの対処法

0. この記事で扱う問題

Kiro IDE の MCP 設定ファイル（mcp.json）で command（例: uvx）や ${VAR} を使って MCP サーバへ接続しようとすると、次のようなエラーで接続できない。

• コマンド起動エラー: Error connecting to MCP server: spawn uvx ENOENT
• 環境変数展開/認証エラー: Failed to create AWS session with profile '${PROFILE}'

この記事は Local MCP server（command / args で起動するタイプ） を中心に扱います。

✅ 結論（原因と解決策）

• MCPサーバ接続失敗原因（よくある2つ）

  1. spawn uvx ENOENT
     Kiro が MCP サーバを起動するとき、command（例: uvx）が Kiro から見える PATH 上に存在しない（または実行権限がない）。
  2. ${VAR} が展開されない / 期待した値にならない
     ${VAR} の展開元は Kiro プロセスが持つ環境変数。加えて Kiro は安全のため 承認済み（Approved）環境変数のみ展開する。

• 解決策

  • Kiro 起動前にシェル（ターミナル）で PATH と必要な環境変数を読み込んでから、同じターミナルで kiro <プロジェクトルート> を実行して起動する。
  • ${VAR} を使う場合は Mcp Approved Env Vars に変数名を追加しておく。

---

1. 前提知識：Kiro の MCP 設定

1.1 MCP 設定ファイルの場所（Workspace / User）

Kiro の MCP 設定は次の2箇所で設定できます。

• Workspace level: <プロジェクトルート>/.kiro/settings/mcp.json（プロジェクト固有）
• User level: ~/.kiro/settings/mcp.json（全プロジェクト共通）
• 両方ある場合は マージされ、同名サーバ定義が衝突した場合は Workspace が優先されます。
  Kiro IDE Docs: MCP Configuration

~/.kiro/
  └── settings/
      └── mcp.json  # User 共通

<プロジェクトルート>/
  └── .kiro/
      └── settings/
          └── mcp.json  # Workspace 固有

1.2 ${VAR} は環境変数参照として推奨

Kiro はセキュリティ上、設定ファイルへの機密値直書きを避け、${VAR} で環境変数参照する形を推奨しています。
Kiro IDE Docs: MCP Configuration

例（公式の雰囲気に寄せたサンプル）:

{
  "mcpServers": {
    "github": {
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

1.3 Mcp Approved Env Vars（承認済み環境変数）

Kiro は安全のため 承認された環境変数のみ ${VAR} として展開します。
未承認の変数が mcp.json に含まれていると、許可を促す警告が表示されます。
Kiro IDE Docs: MCP Security Best Practices (Mcp Approved Env Vars)

• Mcp Approved Env Vars の設定
  

• 未承認のときの警告
  

---

2. アイコンからの起動だとうまくMCP接続できない理由

• mcp.json で ${VAR} を使っても、展開元は Kiro プロセス環境のため アイコン起動で Kiro を立ち上げると、ターミナルで普段読み込まれる ~/.zshrc などが反映されず、PATH や環境変数が不足することがあります。
• また、Kiro の **内蔵ターミナルで後から exportしても、すでに起動している Kiroには反映がされません。

3. 解決策：プロジェクト別 .env を読み込んでから起動する

毎回 export を手打ちするのは面倒なので、以下のやり方にしました。

• プロジェクト配下に .env を置く（.gitignore へ追加しリポジトリ管理しない）
• Kiro 起動前に .env を読み込む
• 同じターミナルで kiro <プロジェクトルート> を実行する

3.1 手順の流れ

• ターミナルで環境を用意 → 同じターミナルで kiro <project> 起動 → MCP接続
  

3.2 手順例：Amazon Bedrock AgentCore 向け（IAM/SigV4 を使う想定）

0) .env を作成（プロジェクトルート）

<プロジェクトルート>/.env

AGENTCORE_MCP_URL=xxxxxxxxxxxxxxxxxxx
PROFILE=default
REGION=ap-northeast-1

1) mcp.json（Workspace）を設定

<プロジェクトルート>/.kiro/settings/mcp.json

{
  "mcpServers": {
    "agentcore-runtime-iam": {
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "${AGENTCORE_MCP_URL}",
        "--service",
        "bedrock-agentcore",
        "--region",
        "${REGION}",
        "--profile",
        "${PROFILE}"
      ],
      "disabled": false
    }
  }
}

2) .env を読み込んで起動

ターミナル（zsh 等）でプロジェクトに移動してから:

cd <プロジェクトルート>
set -a
source .env
set +a
kiro <プロジェクトルート>

---

4. 補足：Kiro 起動ラッパーを ~/bin に置く（プロジェクト別 .env 対応）

毎回.env反映させるコマンドを叩くのも面倒なので、Kiro起動ラッパーを作成します。

4.1 方針

• プロジェクトへ移動
• .env を読み込んで export
• exec kiro <project-path> で起動

4.2 ラッパースクリプト例（kiro-with-env）

#!/usr/bin/env bash
set -euo pipefail

PROJECT="${1:-$(pwd)}"
cd "$PROJECT"

if [[ -f ".env" ]]; then
  set -a
  source ".env"
  set +a
fi

exec kiro "$PROJECT"

---

5. まとめ

• ${VAR} を使う場合は Mcp Approved Env Vars（承認済み環境変数）の設定を忘れない
• 環境変数をKiro起動前に読み込む → 同じターミナルでKiroを起動する