setup-devops-agent

AWS DevOps Agent — Claude のセットアップ

以下の手順は、Claude アプリケーション用の AWS DevOps Agent プラグインをセットアップするためのものです。他のクライアントで使用する場合は、参考としてご利用ください。ただし、クライアント固有の要件に合わせて手順を調整してください。

ステップ 0：セットアップが必要かどうかを確認する

1/ 「aws-devops-agent」MCP サーバーが実行中かどうかを確認します。実行中の場合は、有効な接続があることを確認します（「ステップ 3：接続を確認する」を参照）。

確認に成功した場合は、SigV4 or Bearer Token を使用してプラグインがすでにセットアップ済みであることをユーザーに伝えます。設定を Bearer Token or SigV4 に切り替えられることを提案します。詳しくは、以下の「ステップ 2：認証方式を決定する」を参照してください。

ユーザーが認証設定の変更を希望しない場合は、ここで完了です。先へ進まないでください。

2/ 次の場所に「aws-devops-agent」というキーを持つ MCP サーバー設定があるか確認します。

• プラグインスコープ：${CLAUDE_PLUGIN_ROOT}/.mcp.json
• プロジェクトスコープ：.mcp.json（プロジェクトディレクトリ内、バージョン管理対象）
• プロジェクト固有：.claude/settings.local.json（プロジェクトディレクトリ内）
• ユーザー固有のローカル設定：~/.claude/settings.local.json
• ユーザー固有のグローバル設定：~/.claude/settings.json
• メインの Claude.json：~/.claude.json
• 専用 MCP ファイル：~/.claude/mcp_servers.json

次に、以下を確認します。

• aws-devops-agent キーが存在し、サーバーが接続されている（ツールが利用可能である。「ステップ 3：接続を確認する」を参照）場合 → ユーザーに「DevOps Agent はすでに設定され、接続されています」と伝えます。MCP 設定で Bearer Token が使用されている場合は、代わりに AWS DevOps Agent で SigV4 認証情報を使用するようプラグインをセットアップできることを提案します（複数のエージェントスペース、管理ツール）。MCP 設定で SigV4 認証情報が使用されている場合は、代わりに AWS DevOps Agent で Bearer Token 認証情報を使用するようプラグインをセットアップできることを提案します（単一のエージェントスペース）。
• aws-devops-agent キーが存在するものの、機能していない場合 → 「ステップ 1：現在の状態を診断する」に進みます。
• aws-devops-agent キーが存在しない場合 → 「ステップ 1：現在の状態を診断する」に進みます。

---

ステップ 1：現在の状態を診断する

次の確認を実行します。

# Bearer token
echo "DEVOPS_AGENT_TOKEN: $([ -n "$DEVOPS_AGENT_TOKEN" ] && echo 'set' || echo 'not set')"
echo "DEVOPS_AGENT_REGION: ${DEVOPS_AGENT_REGION:-not set}"

# SigV4 dependencies
uvx --version 2>&1

# AWS credentials
aws sts get-caller-identity 2>&1

以下を判定します。

• bearer_ready = DEVOPS_AGENT_TOKEN が設定されており、かつ DEVOPS_AGENT_REGION が設定されている
• sigv4_ready = aws sts get-caller-identity が成功し、かつ uvx がインストールされている

---

ステップ 2：認証方式を決める

診断の後は、利用可能な方式が 1 つだけの場合でも、必ずユーザーに希望する方式を確認してください。確認できた内容を提示し、ユーザーに選んでもらいます。

エージェントスペースのオペレーターアプリにしかアクセスできない場合は、ベアラートークンを使いたいと思うかもしれません。

複数のエージェントスペースを使う場合や、エージェントスペースを管理する管理者権限がある場合は、SigV4 を使いたいと思うかもしれません。

Bearer の準備状況	SigV4 の準備状況	操作
yes	yes	「ベアラートークンと AWS 認証情報の両方が設定されています。DevOps Agent ではどちらを使いますか？ ベアラートークン（単一のエージェントスペース）または AWS 認証情報／SigV4（複数のエージェントスペースと管理ツール）」
yes	no	「ベアラートークンが設定されています。ベアラートークン（単一のエージェントスペース）を使って DevOps Agent を設定しますか？それとも、AWS 認証情報／SigV4（複数のエージェントスペースと管理ツール）を設定しますか？」
no	yes	「有効な AWS 認証情報があります。SigV4（複数のエージェントスペースと管理ツール）を使って DevOps Agent を設定しますか？それとも、ベアラートークン（単一のエージェントスペース）を設定しますか？」
no	no	「ベアラートークンも AWS 認証情報も設定されていません。ベアラートークン（単一のエージェントスペース）と AWS 認証情報／SigV4（複数のエージェントスペースと管理ツール）のどちらで接続しますか？」その後、選択した方式の手順を案内します。

ベアラートークンを設定したい場合は、AWS のドキュメント DevOps Agent リモートサーバーに接続するを案内するか、このドキュメントの手順に沿ってアクセストークンを作成します。

ユーザーが選択を確定するまで、ステップ 3 に進まないでください。

---

ステップ 3：接続を確認する

「aws-devops-agent」MCP サーバーがすでに実行中の場合は、ツールを一覧表示できるか確認してください。一覧表示できれば、接続は確認済みです。

できない場合は、続行します。

.mcp.json を書き込む前に確認してください。これにより、認証情報が稼働中のエンドポイントで機能することを確認できます。また、既存の MCP サーバー設定の確認にも使用できます。

ベアラートークンの確認

curl -s -w "\nHTTP_STATUS: %{http_code}" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEVOPS_AGENT_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  "https://connect.aidevops.${DEVOPS_AGENT_REGION}.api.aws/mcp"

結果	意味	操作
HTTP 200 + result.tools 配列	成功	ステップ 4 に進む
HTTP 401	トークンが無効または期限切れ	Operator Web App で新しいトークンを作成するようユーザーに伝える
HTTP 403	トークンのスコープが不十分	トークンに agent:read と agent:operate のスコープが必要だと伝える
接続拒否／タイムアウト	エンドポイントに到達できない	SigV4 が利用可能な場合は、代替手段として提案する。それ以外の場合は、利用できないことを報告する。

SigV4 の確認

timeout 30 bash -c '
{
echo "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"setup-check\",\"version\":\"1.0\"}}}"
sleep 0.5
echo "{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\"}"
sleep 0.5
echo "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}"
sleep 8
} | uvx mcp-proxy-for-aws-cli@latest "https://connect.aidevops.${DEVOPS_AGENT_REGION}.api.aws/mcp" --service aidevops --region "$DEVOPS_AGENT_REGION"
'

注： 初回実行では、uvx が mcp-proxy-for-aws-cli とその依存関係をダウンロードするため、10～15 秒かかることがあります。2 回目以降はほぼ瞬時に完了します。

結果	意味	操作
2 行目に result.tools が含まれる	成功	ステップ 4 に進む
出力なし／タイムアウト	認証情報が無効、またはエンドポイントに到達できない	aws sts get-caller-identity を再度確認する
stderr に ExpiredTokenException	AWS セッションの期限切れ	再認証するようユーザーに伝える（aws sso login または認証情報の更新）
AccessDeniedException	IAM 権限が不足	ユーザーのロールに DevOps Agent の権限が必要

ステップ 4：.mcp.json を確認して書き込む

書き込む前に、ユーザーに確認します。

"接続を確認しました。プラグインの .mcp.json に [Bearer token / SigV4] MCP サーバーを追加します。よろしいですか？"

ユーザーが確認してから書き込みます。サーバーエントリは 1 つだけ書き込み、両方を書き込まないでください。MCP 設定は ${CLAUDE_PLUGIN_ROOT}/.mcp.json にインストールします。ワークスペースレベルで MCP サーバーをインストールする方法を案内することもできます。インストール方法は次のとおりです。

• プラグインスコープ：${CLAUDE_PLUGIN_ROOT}/.mcp.json（デフォルト）
• プロジェクトスコープ：.mcp.json（プロジェクトディレクトリ内、バージョン管理対象）
• プロジェクト固有：.claude/settings.local.json（プロジェクトディレクトリ内）

Bearer 設定

{
  "mcpServers": {
    "aws-devops-agent": {
      "type": "http",
      "url": "https://connect.aidevops.${DEVOPS_AGENT_REGION}.api.aws/mcp",
      "headers": {
        "Authorization": "Bearer ${DEVOPS_AGENT_TOKEN}"
      },
      "timeout": 120000
    }
  }
}

SigV4 設定

<REGION> をユーザーの実際のリージョンに置き換えます。

{
  "mcpServers": {
    "aws-devops-agent": {
      "command": "uvx",
      "timeout": 120000,
      "args": [
        "mcp-proxy-for-aws-cli@latest",
        "https://connect.aidevops.<REGION>.api.aws/mcp",
        "--service", "aidevops",
        "--region", "<REGION>"
      ]
    }
  }
}

フォールバック（aws-mcp）

プライマリの aws-devops-agent エンドポイントに接続できず、SigV4 認証情報が利用可能な場合に限り追加します。

{
  "mcpServers": {
    "aws-mcp": {
      "command": "uvx",
      "timeout": 100000,
      "args": [
        "mcp-proxy-for-aws-cli@latest",
        "https://aws-mcp.us-east-1.api.aws/mcp",
        "--metadata",
        "AWS_REGION=us-east-1"
      ]
    }
  }
}

SigV4 のみ：新しい MCP 設定を書き込んだ後、MCP サーバーが正常に書き込まれたことをユーザーに伝えます。次のステップに進みます。

---

ステップ 5：マルチスペースルーティング（SigV4 のみ）

SigV4 のセットアップが成功したら、AgentSpace のルーティングを検出して設定します。

1. 新しく接続した MCP 経由で list_agent_spaces を呼び出し、利用可能なスペースを検出します
2. リストをユーザーに提示します
3. 複数のスペースがある場合は、ルーティングガイドを .claude/aws-agents-for-devsecops.md に書き込みます。

# AWS DevOps Agent — Routing Guide

| Space | Agent Space ID | Purpose |
|-------|----------------|---------|
| <name> | <id> | <ask user> |

1. 特定のスペースを対象とする場合は、すべてのツール呼び出しで agent_space_id を渡すよう指示します。

---

ステップ 6：プラグインを再読み込みする

新しい MCP サーバーを起動するには、ユーザーが /reload-plugins を実行する必要があることを伝えます。ユーザーに実行を促す必要がある場合もあります。また、MCP サーバーを再起動した後、次のプロンプトを試すよう伝えます。

• マルチスペースルーティングのセットアップ（SigV4 のみ）
• ${CLAUDE_PLUGIN_ROOT}/README.md からスキルとプロンプトの候補を一覧表示

---

Bearer トークンのガイダンス（トークンを作成する必要があるユーザー向け）

1. AgentSpace 用の AWS DevOps Agent Operator Web App を開きます

2. Settings → Access tokens → Generate token に移動します

3. Permissions：Operate を指定してトークンを作成します

4. 環境変数を設定します。

   export DEVOPS_AGENT_TOKEN="<your-token>"
   export DEVOPS_AGENT_REGION="<your-region>"
   

   利用可能なリージョン：https://docs.aws.amazon.com/devopsagent/latest/userguide/about-aws-devops-agent-supported-regions.html

5. Claude Code を再起動します（起動元のシェルから環境変数を読み取ります）。

重要： Operate 権限がないと、chat と investigate ツールは失敗するだけでなく、ツールリストに表示されません。

---

SigV4 のガイダンス（AWS 認証情報を設定する必要があるユーザー向け）

1. uvx がインストールされていない場合はインストールします。

   • macOS：brew install uv
   • Linux：curl -LsSf https://astral.sh/uv/install.sh | sh

2. AWS 認証情報を設定します。

   aws configure sso --profile devops-agent
   aws sso login --profile devops-agent
   export AWS_PROFILE=devops-agent
   

3. リージョンを設定します。

   export DEVOPS_AGENT_REGION="<your-region>"
   

4. 確認します：aws sts get-caller-identity

5. IAM ロールには DevOps Agent の権限が必要です（例：aidevops アクセス権を持つ管理ポリシー）。

重要： SigV4 を使用する場合は DEVOPS_AGENT_TOKEN の設定を解除してください。両方が設定されていると、クライアントが署名プロキシではなく Bearer 認証を試みることがあります。

---

トラブルシューティング

エラー	原因	対処方法
ツールが表示されない	トークンが設定されていない、または Claude Code が再起動されていない	DEVOPS_AGENT_TOKEN と DEVOPS_AGENT_REGION を設定して再起動します
HTTP 401	トークンが無効または期限切れ	Operator Web App で新しいトークンを作成します
chat／investigate が表示されない	トークンのスコープが agent:read のみ	agent:operate スコープでトークンを作成します
接続拒否／タイムアウト	エンドポイントに接続できない	ネットワークを確認します。SigV4 が利用可能な場合は、aws-mcp のフォールバックを案内します
ExpiredTokenException	AWS セッション認証情報の期限切れ	aws sso login を実行するか、認証情報を更新します
AccessDeniedException（SigV4）	IAM 権限が不足している	DevOps Agent へのアクセス権を持つロールを使用します
プロキシが起動しない	uvx がインストールされていない	brew install uv（macOS）を実行するか、プラットフォームに応じた方法でインストールします
ツールは表示されるが、呼び出しがタイムアウトする	chat では通常の動作です（5～30 秒）	mcp.json で "timeout": 120000 が設定されていることを確認します