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を起動する