トップ > AIエージェント > 【Kiro CLI/Claude Code/GitHub Copilot Agent Mode】マルチAIコーディングエージェントにおけるmcp.jsonへの環境変数の適用

【Kiro CLI/Claude Code/GitHub Copilot Agent Mode】マルチAIコーディングエージェントにおけるmcp.jsonへの環境変数の適用

AIエージェント Kiro CLI GitHub Copilot Claude Code
記事タイトルとURLをコピーする

こんにちは。
アプリケーションサービス本部、DevOps担当の兼安です。
仕様駆動開発において、AIコーディングエージェントが複数ある方がより効果的な場合があることはご存知でしょうか？
AIコーディングエージェントを複数稼働させる場合、各種設定、例えばMCPサーバーやAPIキーなどの設定を複数箇所に記載する必要が出てきます。
私が知る限り、現状ではこれらの設定を一元管理する標準的な仕組みはないため、今回は私なりに整理してみようと思います。
今回は、VS CodeのCopilot Agent Mode、Claude Code、Kiro CLIの3つのAIコーディングエージェントを対象に、mcp.jsonと同ファイルへの環境変数の適用方法についてまとめてみます。
Codexは現状私の方であまり触れていないため、今回は対象外とさせていただきます。

本記事の検証環境

項目 バージョン
OS macOS Tahoe 26.4.1
VS Code 1.119.0
Claude Code 2.1.126
Kiro CLI 2.2.2
direnv 2.37.1

仕様駆動開発において、AIコーディングエージェントを複数稼働させる理由

仕様駆動開発では、AIが作成した要件定義や設計書を別のAIでレビューすることが有用なことがあります。
これは人間のレビューと同様に、作成者とは異なる視点でのチェックが品質向上につながるためです。
AIコーディングエージェントは同じ基盤モデル（例えばClaude Sonnet）を使っていても、ツールごとにシステムプロンプトやツール統合の仕組みが異なるため、得意・不得意に差があります。
特性の違いから、複数のAIコーディングエージェントを使い分けることで、より多角的なレビューや補完が可能になります。

仕様駆動開発のツールキットであるSpec Kitは30以上のAIコーディングエージェントに対応しており、specify integration switchコマンドでエージェントをいつでも切り替えられるようになっています。

GitHub Spec Kitで複数のコーディングエージェントを使い分けたい - サーバーワークスエンジニアブログ

例えば、Spec Kitで/speckit.specify（仕様作成）を行った後、AIコーディングエージェントだけを別のものに切り替えて/speckit.clarify（仕様の曖昧な部分を明確化）を実行する、といった使い方が想定できます。
（/speckit.clarifyは/speckit.planの前に実行することが推奨されているオプショナルコマンドで、仕様の不明確な箇所を洗い出してくれます。）

各AIコーディングエージェントのmcp.jsonの仕様

各AIコーディングエージェントは、それぞれ異なるパスにMCP設定ファイルを持ちます。
各仕様を表にまとめました。 厳密には各AIコーディングエージェントのMCPサーバーの設定をかける場所は複数あるのですが、今回はプロジェクト単位でMCPサーバーを設定する場合の代表的な場所（パス）を挙げています。
後述の例もそれに則り書いています。

ファイルパス 対応ツール 環境変数の記載方法 環境変数の外部ファイル参照
/.vscode/mcp.json VS Code (Copilot Agent Mode) ${env:VAR} 形式 envFileプロパティで任意のパスを指定可能
/.mcp.json Claude Code ${VAR} 形式 .claude/settings.local.json で定義可能（配置場所は固定）
/.kiro/settings/mcp.json Kiro CLI ${VAR} 形式 なし（起動元シェルの環境変数を継承）

環境変数の外部ファイル参照について

Copilot Agent ModeはenvFileプロパティで任意のパスのファイルを参照できます。そのファイルに環境変数を書いておけば、環境変数として展開されます。

MCP configuration reference

Claude Codeは.claude/settings.local.jsonなどのファイルで環境変数を定義できますが、これらのファイルの配置場所は.claude/配下に固定されます。

Claude Code の設定 - Claude Code Docs

Kiro CLIは、私が調べた限り環境変数の外部ファイル参照機能がないようです。
シンプルに、起動元のシェル環境変数を継承する形になります。

本記事における環境変数の一元管理の方針

上記のとおり、mcp.jsonの設定ファイルがツールごとに分散するのは避けられません。
しかし、mcp.jsonに記載するAPIキーなどの機密情報だけでも一元管理したいところです。
以上を踏まえて、今回は以下のようなディレクトリ構成で、.env.localをAPIキーの一元管理ファイルとして使います。

.
├── .envrc                       # direnv 設定（dotenv_if_exists .env.local）
├── .env.local                   # 実際のAPIキーを記載（.gitignore でGit管理対象外とする）
├── .env.local.sample            # .env.local のテンプレート（Git 管理対象）
├── .kiro/
│   └── settings/
│       └── mcp.json             # Kiro CLI 用（${VAR} で環境変数を参照）
├── .mcp.json                    # Claude Code 用（${VAR} で環境変数を参照）
├── .claude/
│   ├── settings.json            # .env ファイルの読み取り拒否などの共通ポリシーを定義
│   └── settings.local.json      # MCP ツールの許可リストなど個人ごとの権限設定（.gitignore でGit管理対象外とする）
└── .vscode/
    └── mcp.json                 # Copilot agent mode 用（envFile で .env.local を参照）

Claude Codeについては、.claude/settings.local.jsonに環境変数を記載する方法もありますが、今回はあえてdirenvに任せる方針を採りました。
こうすることで、.env.local1ファイルに環境変数を集約でき、Kiro CLIとも共通の仕組みで管理できると考えました。
.claude/settings.jsonと.claude/settings.local.jsonは、一応載せていますが今回の話のメインではないので、今回は触れません。

今回のMCPサーバーの構成

今回の構成では、以下の3つのMCPサーバーを使用しています。

AWS MCP（aws-mcp）

先日GAされたAWS公式のMCPサーバーです。mcp-proxy-for-aws経由でAWS MCPエンドポイントに接続し、AWSリソースの確認・作成・変更などの操作を行います。リージョンはap-northeast-1（東京）を指定しています。

AWS Knowledge MCP サーバーの一般提供開始 - AWS

IAM Policy Autopilot（iam-policy-autopilot）

IAMポリシーの作成・分析・最適化に特化したMCPサーバーです。ソースコードから必要最小限のIAMポリシーを自動生成するなど、IAM関連の操作を効率化できます。
私は本記事執筆時点（2026/05/11）ではAWS MCPと併用した方が無難と考えています。

GitHub MCP Server（github）

GitHub公式のMCPサーバーです。
GitHub Actionsのログ取得など、単純なgitコマンドやGitHub CLIでは取得しにくい情報へのアクセスに便利です。
GitHub MCPサーバーは認証にPersonal Access Token（PAT）が必要で、環境変数GITHUB_PERSONAL_ACCESS_TOKENで渡します。
このPATの管理が、今回の環境変数一元管理の具体的なユースケースとなります。

direnvと.env.localによる環境変数の一元管理

direnvは、ディレクトリごとに環境変数を自動で設定・解除してくれるシェル拡張ツールです。
プロジェクトのルートに.envrcファイルを配置しておくと、そのディレクトリにcdした時、同ファイルに記載されたファイルから環境変数が自動的にロードされます。
ディレクトリを離れると、これらの環境変数は自動的に解除されます。

今回のリポジトリでは.envrcに以下の1行だけを書いています。

dotenv_if_exists .env.local

これは「.env.localが存在すれば、その内容を環境変数として読み込む」という指示です。.env.localには以下のようにAPIキーを記載します。

GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

.env.localは.gitignoreに含まれているため、Gitにコミットされません。テンプレートとして.env.local.sampleをGit管理対象としており、リポジトリをクローンした際はこれをコピーして使います。

cp .env.local.sample .env.local
# .env.local を編集して実際のトークンを記載
direnv allow   # .envrc の読み込みを許可（初回や .envrc 変更時に必要）

direnv allowは、direnvのセキュリティ機構により必要なコマンドです。
悪意のあるリポジトリをクローンした際に.envrc内のコードが自動実行されるのを防ぐため、direnvは明示的に許可されるまで.envrcを読み込みません。

direnv – unclutter your .profile | direnv

The security mechanism didn't allow to load the .envrc. Since we trust it let's allow its execution

$ direnv allow .

なお、環境変数名はGITHUB_TOKENは一旦避けるべきと考えています。
私が検証していた時、GITHUB_TOKENという環境変数を作ると、VS CodeのOAuth認証フローと競合するような挙動が見られました。
回避策はあるかもしれませんが、GitHub MCP ServerのPAT用の環境変数はGITHUB_PERSONAL_ACCESS_TOKENなので、こちらに合わせた方が無難かと思います。

各AIコーディングエージェントの環境変数展開の挙動

GitHub Copilot Agent Modeの場合

設定ファイルのパスは.vscode/mcp.jsonです。
githubのenvFileプロパティに着目してください。
envFileを使うことで、.env.localから環境変数を読み込むことができます。
.env.localからGITHUB_PERSONAL_ACCESS_TOKENを読み込み、-eオプションでDockerコンテナに渡しています。

// GitHub Copilot Agent Modeの.vscode/mcp.json
{
    "servers": {
        "iam-policy-autopilot": {
            "command": "uvx",
            "args": ["iam-policy-autopilot", "mcp-server"],
            "env": {
                "AWS_REGION": "ap-northeast-1"
            }
        },
        "aws-mcp": {
            "command": "uvx",
            "args": [
                "mcp-proxy-for-aws@latest",
                "https://aws-mcp.us-east-1.api.aws/mcp",
                "--metadata", "AWS_REGION=ap-northeast-1"
            ]
        },
        "github": {
            "command": "docker",
            "args": [
                "run", "-i", "--rm",
                "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
                "ghcr.io/github/github-mcp-server"
            ],
            "envFile": "${workspaceFolder}/.env.local"
        }
    }
}

envFileを使わない場合、Copilot Agent Modeでは${env:VAR}形式で環境変数を直に参照できます。
GitHub MCP Serverであれば、以下のようにenvブロックで${env:GITHUB_PERSONAL_ACCESS_TOKEN}を指定すれば、VS Codeプロセスの環境変数から展開されます。

// GitHub Copilot Agent Modeの.vscode/mcp.json
{
    "servers": {
        // 途中省略
        "github": {
            "command": "docker",
            "args": [
                "run", "-i", "--rm",
                "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
                "ghcr.io/github/github-mcp-server"
            ],
            "env": {
                "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_PERSONAL_ACCESS_TOKEN}"
            }
        }
    }
}

ただし、この書き方だとdirenvでセットした環境変数が読み込まれない可能性があります。
これは、GitHub Copilot Agent Modeというより、direnvとVS Codeの起動順番によるものです。
VS Codeがmcp.jsonを読み込むタイミングで、VS Codeプロセスの環境変数にdirenvでセットした値がまだ反映されていない可能性があるため、うまく展開されないということが起こります。
コマンドでディレクトリ移動してからVS Codeを起動すればうまく展開させることはできますが、日々の作業において現実的な手段とは思えません。
したがって、GitHub Copilot Agent Modeで安定して環境変数を展開させるためには、envFileプロパティを使って.env.localから直接読み込む方法がよいと思います。

Claude Code / Kiro CLIの場合

Claude Code（.mcp.json）やKiro CLI（.kiro/settings/mcp.json）の場合は、環境変数の参照方法だけが異なります。

// Claude Codeの.mcp.json
{
    "mcpServers": {
        // 途中省略
        "github": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "GITHUB_PERSONAL_ACCESS_TOKEN",
                "ghcr.io/github/github-mcp-server"
            ],
            "env": {
                "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
            }
        }
    }
}
// Kiro CLIの.kiro/settings/mcp.json
{
    "mcpServers": {
        // 途中省略
        "github": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "GITHUB_PERSONAL_ACCESS_TOKEN",
                "ghcr.io/github/github-mcp-server"
            ],
            "env": {
                "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
            }
        }
    }
}

こちらはenvFileではなくenvブロックで${GITHUB_PERSONAL_ACCESS_TOKEN}を直接参照しています。
この環境変数はdirenv経由でシェルにセットされている前提です。

Claude Codeに関しては、.claude/settings.local.jsonに環境変数を記載する方法もありますが、そうすると環境変数の管理が分散してしまうため、今回はあえてdirenvに任せる方針を採りました。
.claude/settings.local.jsonに環境変数を記載する場合は、.mcp.jsonにenvプロパティが不要となるので書き方を少し変える必要があります。

// Claude Codeの.claude/settings.local.json
{
    "permissions": {
        "allow": [
            // 途中省略
        ]
    },
    "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "PAT文字列"
    },
    "enabledMcpjsonServers": [
        "iam-policy-autopilot",
        "aws-mcp",
        "github"
    ]
}

// Claude Codeの.mcp.json
{
    "mcpServers": {
        // 途中省略
        "github": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "GITHUB_PERSONAL_ACCESS_TOKEN",
                "ghcr.io/github/github-mcp-server"
            ]
        }
    }
}

今回は以上です。
今回はdirenvを使用しましたが、Dev Containers（devcontainer）を使用すればまた違った管理方法も可能になると思うので、それが見えたらまた記事にまとめてみたいと思います。

関連記事

MCPサーバーの設定におけるAPIキーなどの管理方法については、以下の記事で別のアプローチも紹介しています。こちらも参考にしてみてください。

blog.serverworks.co.jp

兼安 聡(執筆記事の一覧)

アプリケーションサービス本部 DS3課
2025 Japan AWS Top Engineers (AI/ML Data Engineer)
2025 Japan AWS All Certifications Engineers
2026 AWS Community Builders(2年目)
Certified ScrumMaster
PMP
広島在住です。今日も明日も修行中です。
X(旧Twitter)