自立型のコーディングエージェントをAWS上で管理しているアプリに導入する場合、エージェントによるAWSリソースへのアクセス権の管理が課題になりがちです。CloudWatch系のログやメトリクス分析やCloudFormation・CodeDeployなどのデプロイエラー分析、または新機能追加時のアーキテクチャ相談など、さまざまなケースでエージェントにAWSリソースの情報を与える必要が生まれます。
一方で、エージェントに長期のアクセスキーを渡すのは避けたいところです。鍵の保管とローテーションが新しい運用負担になり、漏洩したときの被害も大きくなります。
CircleCI の AI エージェント Chunk は、CircleCI が提供する OpenID Connect (OIDC) ID トークン を使うことで、長期のアクセスキーを持たずに AWS へアクセスできます。本記事では、Chunk から AWS リソースを「読み取り専用」で安全に参照できるようにするまでを紹介します。
Chunkを利用してAWSリソースにアクセスする方法
CircleCIのChunkからの接続には３つの設定が必要です。
１つ目はOIDCを利用した接続設定です。CircleCIがアクセスする際に利用するIAMロールの設定や、CircleCI側にARNの設定などを行います。続いてリポジトリ側に２つの設定ファイルを作成します。1つ目は.circleci/chunk.jsonです。これはChunkが利用できるMCPサーバーの設定や環境変数の定義を行うファイルです。そしてもう１つは.claude/settings.jsonです。ChunkはClaude Agent SDKを利用して構築されたエージェントです。そのため、Claude Codeなどで使う設定ファイルを利用したカスタマイズが一部可能です。
1:事前準備
事前にChunkのセットアップと、AWSへのOIDCプロバイダーの登録を済ませておきましょう。設定方法は以下の２記事にて紹介しております。
2: Chunk 専用の ReadOnly ロールを用意する
まずChunkエージェントが利用するIAMロールを用意しましょう。今回はすでにOIDC連携の設定は完了しているものとして、Chunkエージェント用のIAMロールを用意する手順だけを紹介します。
既存の CI/CD パイプラインで使っているフル権限の IAM ロールを、Chunk に流用しないでください。AI エージェントは自律的に判断して動くため、与えた権限の範囲内で想定外の操作をする可能性があります。Chunk 専用に、ReadOnlyAccess だけを付けた別のロールを作るのが安全です。
IAM の ID プロバイダには、CircleCI 組織の OIDC プロバイダ（oidc.circleci.com/org/<組織 ID>）が登録済みです。
IAM ロールを新規作成し、信頼されたエンティティタイプに「ウェブアイデンティティ」を選びます。CircleCI の OIDC トークンでロールを引き受けるためです。
アイデンティティプロバイダーには先ほどの CircleCI OIDC プロバイダ、Audience には組織 ID を指定してください。
許可ポリシーには ReadOnlyAccess を選びます。AWS のリソースを参照できる一方、作成・変更・削除はできません。実際の運用では、必要最小限のリソースのみアクセスできるようにすることをお勧めします。
ロール名を付けます。CI/CD 用のロールと区別できるよう、Chunk 専用とわかる名前にします。今回は hidetaka-cci-chunk-readonly-role としました。
ロールが作成されると ARN が表示されます。この ARN を、コピーしましょう。
CircleCIのOrganization設定から、Contextページを開きましょう。Chunkのセットアップが完了していれば、circleci-agents コンテキストが作成されています。これは Chunk 自身が使うコンテキストです。
circleci-agents コンテキストを開き、先ほど作成したIAMロールのARNを AWS_ROLE_ARN という名前で追加しましょう。
続いてAWS_ACCOUNT_ID を追加します。
最後にCHUNK_EXPERIMENTAL_MCP_SERVERS をtrueで登録しましょう。これはMCP サーバーを Chunk に認識させるための値です。
これで３つのシークレットが登録されたことになります。
これでChunkエージェントがAWSリソースへアクセスするために必要な値の設定が完了しました。
続いてAWSリソースにアクセスするためのMCPサーバーを設定します。
3: chunk.json に AWS MCP サーバーを登録する
.circleci/chunk.json は Chunk 用の設定ファイルです。ここに任意のMCPサーバーを登録することで、Chunkが外部サービスにアクセスできるようになります。
今回はAWS を操作する MCP サーバー awslabs.aws-api-mcp-server を登録しましょう。
chunk.json には、OIDC トークンをファイル化するラッパーを含めています。また、リージョンを固定値で記載していますので、ap-northeast-1以外のリージョンへアクセスさせたい場合は、AWS_REGIONを変更してください。
{
"mcpServers": {
"awslabs.aws-api-mcp-server": {
"command": "bash",
"args": [
"-c",
"OIDC_FILE=$(mktemp /tmp/oidc-XXXXXX.token); trap 'rm -f \"$OIDC_FILE\"' EXIT INT TERM; printf '%s' \"$CIRCLE_OIDC_TOKEN\" > \"$OIDC_FILE\"; unset CIRCLE_OIDC_TOKEN; export AWS_WEB_IDENTITY_TOKEN_FILE=\"$OIDC_FILE\"; exec uvx awslabs.aws-api-mcp-server@1.3.45"
],
"env": {
"CIRCLE_OIDC_TOKEN": "${CIRCLE_OIDC_TOKEN}",
"AWS_ROLE_ARN": "${AWS_ROLE_ARN}",
"AWS_REGION": "ap-northeast-1",
"AWS_ACCOUNT_ID": "${AWS_ACCOUNT_ID}",
"READ_OPERATIONS_ONLY": "true"
}
}
}
}
READ_OPERATIONS_ONLY を true にしているのは、書き込み系 API を MCP サーバー側でも拒否させるためです。IAM ロールの ReadOnlyAccess と合わせて、二重の安全策になります。
OIDC トークンを AWS SDK が読める形に変換する
CircleCI は JWT を CIRCLE_OIDC_TOKEN という環境変数で渡します。一方、AWS SDK の Web Identity 連携は AWS_WEB_IDENTITY_TOKEN_FILE（ファイルパス）を要求します。この形式の不一致が原因で、環境変数のままでは認証に失敗します。
対策として、MCP サーバーの起動を bash ラッパーにして、トークンを一時ファイルに書き出してから MCP を exec します。前掲の chunk.json の args がそのラッパーです。具体的には、mktemp で一時ファイルを作って CIRCLE_OIDC_TOKEN の中身を書き込み、そのパスを AWS_WEB_IDENTITY_TOKEN_FILE に渡して MCP サーバーを起動します。トークンをファイルにもプロセス環境にも残さないよう、trap でプロセス終了時に一時ファイルを削除し、書き込み後は unset CIRCLE_OIDC_TOKEN で環境変数からトークン本体を消しています。
これでAWS MCPサーバーを使う準備ができました。続いてAWS MCPサーバーを実際に動かすために必要な幾つかの設定を行います。
もう 1 つのハマりどころが、uvx が PATH にないことです。Agent セッションの開始時点では uv / uvx がまだ入っていないため、起動コマンドが uvx 直接呼び出しだとコマンド自体が見つかりません。これは次のセクションの cci-agent-setup.yml で uv を事前にインストールすることで解決します。
4: cci-agent-setup.yml で実行環境を整える
.circleci/cci-agent-setup.yml は、Chunk の実行環境を準備するファイルです。ここで定義したジョブがChunkエージェントを実行する前に動作します。ここではMCPサーバーを動かすために必要なuvのインストールと、AWSとのOIDC連携を効率的に行うためのOrbの設定を行います。
version: 2.1
orbs:
aws-cli: circleci/aws-cli@5
workflows:
cci-agent-setup:
jobs:
- cci-agent-setup
jobs:
cci-agent-setup:
docker:
- image: cimg/node:22.14
steps:
- checkout
- aws-cli/setup:
role_arn: ${AWS_ROLE_ARN}
region: ap-northeast-1
- run:
name: Install uv
command: |
curl -LsSf https://astral.sh/uv/0.11.23/install.sh | sh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$BASH_ENV"
- run:
name: Install Node dependencies
command: |
corepack enable
corepack prepare pnpm@10.32.1 --activate
pnpm install --frozen-lockfile
AWS CLIのOrbを入れることで、OIDC による一時クレデンシャルの設定を効率化できます。role_arn を使って認証し、AWS のクレデンシャルをジョブ環境に注入してくれます。
5: settings.json で MCP ツールを許可する
認証と MCP 定義が整っても、エージェントがツールを呼ぶ段階で permissions に阻まれます。 .claude/settings.json の permissions.allow に、AWS MCP ツールを追加しましょう。
{
"permissions": {
"allow": [
"Bash(chunk:*)",
"mcp__awslabs_aws-api-mcp-server__call_aws"
]
}
}
ツール名は mcp__{サーバー名}__{ツール名} の形式です。この行を追加しないと、Chunk の非インタラクティブ実行ではツール呼び出しが拒否されます。
これでChunkがAWSリソースへアクセスできる準備ができました。
Chunk に AWS リソースを調べさせる
実際に Chunk へ AWS リソースを調べさせてみましょう。今回はAWS上にリソースのないアプリで検証を行なっていたため、アーキテクトの相談を行うことにします。
このアプリを AWS へデプロイするならどこが最適か。
既存の S3 バケットで推奨すべきものがあれば提案してほしい。
AWS Amplify に既にプロジェクトがあるかも報告してほしい。リージョンは us-west-2
というプロンプトを送信したところ、数分でレポートが作成されました。
まとめ
CircleCIのChunkエージェントでは、CICDで利用するOIDC認証の仕組みを利用してAWS等のリソースへアクセスさせることができます。Claude Agent SDKを利用して構築されたエージェントであることなどを理解した上で設定する必要がありますが、CICD用のIAMロールとは別のAI向けに作成したロールを用意するだけでアクセスを制御することが可能です。