はじめに
AWS DevOps Agent（サービス名 aidevops）を Claude Code から呼べるようにしました。
ついでにMCPとAWS-APIを叩くのとで比較検討してみようと思い、AWS APIをたたく自作SKkillも作っています。
- セットアップ手順と、それぞれのハマりどころ
- 同じ質問を両方に投げて回答を比較（ap-northeast-1 の DocumentDB の未適用パッチ調査）
- 回答が食い違った原因の追試と考察
をまとめています。結論だけ先に書くと、
- セットアップは 「MCP を主、スクリプトを従」 が落とし所
- 回答は一度食い違ったが、追試すると **原因は経路ではなく
「エージェントがドキュメント検証ツールを呼んだかどうか」**だった。
同一文面で聞き直したら両経路とも正答した - つまり 精度を左右するのはプロンプトの書き方。経路選択で悩む意味はあまり無い
- クレジット消費量はタスクが小さすぎてほぼ比較できず。
本記事の AWS アカウント ID・AgentSpace ID・DB クラスタ名はマスク/改変している。
日付は実際の検証日（2026-09-17）のまま。
前提環境
| 項目 | バージョン |
|---|---|
| aws-cli | 2.34.32 |
| botocore（system python3.14） | 1.43.64（devops-agent サービスモデルを含む） |
| mcp-proxy-for-aws | 1.7.0 |
| AgentSpace |
ap-northeast-1、locale ja-JP
|
| DevOps Agent API バージョン | 2026-01-01 |
方法A: AWS API を直接叩く自作 Skill
A-1. そもそも何というサービスなのか
最初は「Bedrock Agent だろう」と当たりを付けたが外れた。
$ aws --profile origin bedrock-agent list-agents
# → awslens 系や sechub 系は出るが DevOpsAgent は無い
$ aws --profile origin bedrock-agentcore-control list-agent-runtimes
{ "agentRuntimes": [] }
正解は IAM ロールから辿れた。
$ aws --profile origin iam list-roles | grep -i devops
DevOpsAgentRole-AgentSpace-xxxxxxxx
DevOpsAgentRole-WebappAdmin-xxxxxxxx
信頼ポリシーの Principal が aidevops.amazonaws.com、SourceArn が
arn:aws:aidevops:ap-northeast-1:<account-id>:agentspace/* になっていた。
独立したサービス aidevops（AWS DevOps Agent） で、aws-cli では aws devops-agent として生えている。
$ aws --profile origin devops-agent list-agent-spaces --max-results 10
{
"agentSpaces": [
{
"name": "my-devops-agent",
"locale": "ja-JP",
"agentSpaceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
]
}
ハマりどころ(1): list-agent-spaces は --max-results を付けないと空の {} が返ってきた。
付けると普通に一覧が出る。最初これで「権限が無いのか?」と 10 分溶かした。
A-2. aws-cli では chat できない
チャットの API は CreateChat → SendMessage → レスポンスを受け取る、という流れ。
ところが aws-cli には send-message サブコマンドが存在しない。
$ aws devops-agent send-message ...
aws: [ERROR]: argument operation: Invalid choice 'send-message'
$ aws devops-agent help | grep -c . # create-chat / list-chats / list-pending-messages はある
サービスモデルを見ると理由が分かる。SendMessage のレスポンスが eventstream（ストリーミング）だから。
# botocore/data/devops-agent/2026-01-01/service-2.json
"SendMessageEvents": {
"type": "structure",
"documentation": "responseCreated -> responseInProgress ->
(contentBlockStart/Delta/Stop) -> responseCompleted|responseFailed",
"eventstream": true
}
aws-cli v2 は eventstream 出力のオペレーションを公開しない。
つまり CLI だけでは会話できず、SDK（botocore）を直接使うしかない。
A-3. botocore ラッパを書く
イベントループの中核だけ抜粋。(正確に言うとClaude Codeに書かせています)
resp = client.send_message(agentSpaceId=space, executionId=execution_id, content=text)
block_types = {}
for event in resp["events"]:
(kind, body), = event.items()
if kind == "contentBlockStart":
block_types[body.get("index")] = body.get("type")
elif kind == "contentBlockDelta":
delta = body.get("delta", {})
btype = block_types.get(body.get("index"), "text")
chunk = (delta.get("textDelta", {}).get("text")
or delta.get("jsonDelta", {}).get("partialJson") or "")
if btype in TEXT_TYPES: # 本文だけ stdout
sys.stdout.write(chunk); sys.stdout.flush()
elif kind == "responseFailed":
failed = body
ハマりどころ(2): content block には本文（type 未設定 or text）以外に
context_usage / final_response / chat_title という内部ブロックが流れてくる。
素直に全部 stdout に流すと、同じ回答が二重に出たりコンテキスト使用率の JSON が混ざったりする。
ハマりどころ(3): プロジェクトの venv に入っていた botocore 1.42.27 には devops-agent の
サービスモデルが無かった。システム側の 1.43.64 には有る。
#!/usr/bin/env python3 だと venv 側を掴んで死ぬので #!/usr/bin/python3 固定にした。
A-4. Claude Code の Skill として登録
~/.claude/skills/devops-agent/SKILL.md を置くだけ。
---
name: devops-agent
description: AWS DevOps Agent に質問し回答を受け取る。インシデント調査、リソース状況の確認、
推奨事項の参照をさせたいとき、または /devops-agent で呼び出されたときに使う。
---
# AWS DevOps Agent を呼び出す
~/.claude/skills/devops-agent/devops-agent.py ask "ECS の直近の異常を調べて"
~/.claude/skills/devops-agent/devops-agent.py ask --chat <executionId> "その原因は？"
## 注意
- 応答は数十秒〜数分。Bash tool の timeout を 600000ms 程度にして呼ぶこと。
- 質問は日本語でよい（AgentSpace の locale が ja-JP）。
あとは ~/.claude/settings.json の permissions.allow にスクリプトのパスを足して、毎回の許可ダイアログを消す。
ここまでの所要: 実質半日（API の特定とイベントストリームの解釈が大半）。
方法B: 公式リモート MCP サーバー
次にAWS公式が出しているMCP サーバー。
https://connect.aidevops.{region}.api.aws/mcp
ap-northeast-1 でも生きている（未認証で叩くと 401 が返る=到達している）。
B-1. 認証は2択
| 方式 | 内容 | 向き |
|---|---|---|
| Bearer トークン | コンソールで access token 機能を有効化 → Web アプリでトークン発行。read / operate スコープ、有効期限 1〜60日、IP 許可リスト可 |
個人利用・単一 AgentSpace |
| SigV4 |
uvx mcp-proxy-for-aws@latest がローカルの AWS 認証情報で署名。トークン発行不要 |
複数 AgentSpace・既存の IAM 統制に乗せたい場合 |
SigV4 を選んだ。理由は、60日ごとのトークン更新・失効運用を持ちたくないことと、
既に ~/.aws/config にプロファイルがあるのでそれをそのまま使えること。
B-2. .mcp.json を手書きする
{
"mcpServers": {
"aws-devops-agent": {
"type": "stdio",
"command": "uvx",
"args": [
"mcp-proxy-for-aws@latest",
"https://connect.aidevops.ap-northeast-1.api.aws/mcp",
"--service", "aidevops",
"--region", "ap-northeast-1"
],
"env": { "AWS_PROFILE": "origin" },
"timeout": 120000
}
}
}
これだけ。Claude Code を再起動（または /mcp で承認）すると 35 個のツールが生える。
list_agent_spaces, get_agent_space, create_agent_space, update_agent_space,
create_access_token, get_access_token, list_access_tokens, revoke_access_token, rotate_access_token,
list_services, get_service, list_associations,
create_investigation, create_custom_agent_task, get_task, list_tasks, list_executions,
list_journal_records, list_recommendations, get_recommendation, update_recommendation,
list_goals, start_evaluation,
create_release_testing_job, cancel_release_testing_job,
get_release_ui_testing_report, get_release_api_testing_report,
create_release_readiness_review, cancel_release_readiness_review, get_release_readiness_report,
create_chat, list_chats, chat, investigate, send_message
自作スクリプトは chat 相当しか実装していなかったので、機能差は歴然。
特に investigate（5〜8分かけて非同期で根本原因分析）は自前実装が現実的でない。
B-3. --read-only は罠だった
mcp-proxy-for-aws には --read-only フラグがある。参照専用で繋ぎたかったので付けてみた。
$ (cat init.jsonl; sleep 20) | uvx mcp-proxy-for-aws@latest <endpoint> \
--service aidevops --region ap-northeast-1 --read-only | ...
read-only tools: 0
ハマりどころ(4): --read-only を付けると ツールが 0 個になる。
このサーバーのツール定義に readOnlyHint アノテーションが無いため、
プロキシ側のフィルタが全部落としてしまう。chat すら消えるので、付けると何もできないサーバーになる。
代わりに Claude Code 側の permissions.deny でツール名を名指しして塞いだ。
{
"permissions": {
"deny": [
"mcp__aws-devops-agent__create_access_token",
"mcp__aws-devops-agent__rotate_access_token",
"mcp__aws-devops-agent__revoke_access_token",
"mcp__aws-devops-agent__create_agent_space",
"mcp__aws-devops-agent__update_agent_space",
"mcp__aws-devops-agent__update_recommendation"
]
}
}
chat / investigate / 参照系は残しつつ、アカウント構成とトークン管理だけ塞げる。
もっと硬くするなら SigV4 なので IAM 側で aidevops:*AccessToken 等を Deny するのが本当の強制力になる。
B-4. 公式プラグインという選択肢（採らなかった）
Claude Code には公式マーケットプレイスに aws-agents-for-devsecops（AWS 製、v1.1.0）がある。
/aws-agents-for-devsecops:setup-devops-agent でセットアップウィザードが走る。
採用しなかった理由:
- 同梱の
.mcp.jsonが Bearer トークン前提（${DEVOPS_AGENT_TOKEN}、region 既定us-east-1） - セットアップ Skill で SigV4 に切り替えられるが、書き込み先の既定が
${CLAUDE_PLUGIN_ROOT}/.mcp.json
（=プラグインのキャッシュディレクトリ内）なので、プラグイン更新で消える可能性がある - AWS Security Agent が抱き合わせで、skills 10個 + commands 9個が毎セッションのリストに載る
- 使うパッケージがドキュメントと違い
mcp-proxy-for-aws-cli@latest
インシデント調査のワークフロー Skill ごと欲しいなら価値はある。今回は DevOps Agent を呼べれば十分だった。
組織承認について: Claude の Team プランでも、組織側の managed settings
（strictKnownMarketplaces / allowedMcpServers / allowManagedMcpServersOnly 等）が
未設定なら公式プラグインの導入に組織承認は要らなかった。出るのはローカルの信頼確認ダイアログだけ。
セットアップ比較
| 軸 | 公式リモート MCP (SigV4) | 自作 Skill（AWS API 直叩き） |
|---|---|---|
| 構築コスト |
.mcp.json 15行、10分
|
API 特定+eventstream 実装で半日 |
| 機能範囲 | 35 ツール（investigate / recommendations / release testing / backlog…） |
chat 相当のみ |
| モデルの自律利用 | Claude が自分でツールを選ぶ | Bash 経由。こちらでコマンドを組み立てる必要 |
| コンテキスト消費 | ツール定義で常時 約3.9k tokens/セッション（15.4KB） | Skill の説明1行のみ（呼ぶまでほぼゼロ） |
| 非同期処理 |
get_task ポーリング等をツールで提供 |
非対応 |
| 依存 |
uvx + PyPI 解決（初回 10〜15秒） |
system の botocore のみ。CI・パイプ向き |
| 権限制御 |
permissions.deny でツール単位（--read-only は使えない） |
送れる API がチャット系に限定 |
| 保守 | AWS 公式が追従 | eventstream パースを自前で維持 |
同じ質問を両方に投げてみた
両方に、ほぼ同じ質問を投げて回答を比べた。
ap-northeast-1 の DocumentDB クラスタとインスタンスを一覧し、
pending maintenance action（未適用パッチ）が残っているものを特定してください。
適用予定日・強制適用期限・OptInStatus も示してください。
エンジンバージョンが最新でないものがあれば指摘してください。
先に断っておくと、この最初の比較は厳密な A/B テストになっていない。
2回の質問文が一字一句同じではなく（片方は CurrentApplyDate / OptInStatus を明示、
もう片方は「現在適用待ちかどうか」と書いた）、実行タイミングも数分ずれている。
この点は後述の「なぜ差が出たのか」で追試して詰める。
どちらの経路でも、エージェント側は自分で docdb.describe_db_clusters /
describe_db_instances / describe_pending_maintenance_actions を叩いて答えてくれる。
こちらが事前に情報を集めて渡す必要はない。
結果(1): 未適用パッチの列挙 → 一致・正しい
両者とも同じ結論に到達した。
| 対象 | アクション | 内容 | CurrentApplyDate | AutoAppliedAfterDate | OptInStatus |
|---|---|---|---|---|---|
cluster docdb-xxxx-mrr
|
system-update |
Bug Fixes | 2026-09-17 17:49 UTC | 2026-10-07 11:17 UTC | next-maintenance |
AWS API で裏取りしても一致。
$ aws --profile origin docdb describe-pending-maintenance-actions
cluster:docdb-xxxx-mrr | system-update | Bug Fixes
| current: 2026-09-17T17:49:00+00:00 | autoAfter: 2026-10-07T11:17:27+00:00 | optIn: next-maintenance
なお Skill 経由のほうが丁寧で、同アカウントの RDS インスタンス2台にも
OS 更新の system-update が pending であることに触れた上で「DocumentDB ではないので対象外」と明示していた。
MCP 経由の回答にはこの言及が無かった。
結果(2): エンジンバージョン → 食い違った
ここで両者の答えが割れた。
| 経路 | 回答 |
|---|---|
| MCP 経由 | 「DocumentDB の最新は 5.0。4.0 の2クラスタは旧世代。なおメジャーバージョンアップはインプレース不可でスナップショットリストア移行が必要」 |
| Skill 経由 | 「最新は 8.0.1。4.0 の2クラスタは2世代古い。2026年8月31日から 4.0 → 8.0 の直接インプレースアップグレードがサポートされた」 |
AWS API で決着をつけた。
$ aws --profile origin docdb describe-db-engine-versions --engine docdb \
--query 'DBEngineVersions[].[EngineVersion,ValidUpgradeTarget[].EngineVersion]'
3.6.0 → [5.0.0, 5.0.1, 8.0.0, 8.0.1]
4.0.0 → [5.0.0, 5.0.1, 8.0.0, 8.0.1]
5.0.0 → [5.0.1, 8.0.0, 8.0.1]
5.0.1 → [8.0.0, 8.0.1]
8.0.0 → [8.0.1]
8.0.1 → []
Skill 経由が正解。最新は 8.0.1 で、4.0.0 からは 8.0.1 への直接アップグレードパスが存在する。
MCP 経由の回答は「最新バージョン」も「インプレース不可」も誤りだった。
なぜ差が出たのか — 追試と見解
「MCP 経由のほうが精度が低いのでは」と早合点しそうになったが、そう結論する前に追試した。
追試: 同一文面でバージョンだけを聞く
複合質問をやめ、一字一句同じ文面をバージョンの件だけに絞って両経路に投げた。
Amazon DocumentDB の最新エンジンバージョンは何ですか。また 4.0 から直接インプレース
アップグレードできますか。判断の根拠（どの情報源・どのAPIで確認したか）も明示してください。
結果は 両経路とも正答、しかも回答の中身がほぼ一致した。
| 経路 | 最新バージョン | 4.0 → 8.0 直接 MVU | 根拠として挙げたもの |
|---|---|---|---|
| MCP 経由 | 8.0（8.0.1） | 可能 | リリースノート2026-08-31、docdb-mvu.html。verify_aws_claim で公式ドキュメントをリアルタイム検索したと明記 |
| Skill 経由 | 8.0（8.0.1） | 可能 | 同上 + バージョンサポート期限表。**「verify_aws_claim（AWSドキュメント検索）を2クエリ実行。学習データではなく取得時点の公式ドキュメントに基づく」**と明記 |
MCP 経由の回答にはご丁寧に
⚠️ 補足：今回はドキュメント検索で確認しており、実際にあなたのアカウントの DocumentDB
クラスターに対して API 呼び出しは行っていません。
とまで書いてあった。再現性のある差ではなかった。
見解
追試を踏まえた私の解釈は以下のとおり。
1. 経路（MCP / API直叩き）は精度に関係しない
これは構造的に当然で、MCP サーバーは同じ aidevops API のラッパに過ぎない。
chat ツールの実体は CreateChat + SendMessage であり、mcp-proxy-for-aws がやっているのは
SigV4 署名とプロトコル変換だけ。同じ AgentSpace・同じエージェント・同じモデルに届く。
精度差が出るとしたら経路ではなく、渡したプロンプトか、その実行でのツール選択しかない。
2. 実際の分岐点は「ドキュメント検証ツールを呼んだかどうか」
このエージェントは verify_aws_claim という公式ドキュメントを実時間で検索するツールを持っている。
2つの実行を並べるとこうなる。
| 呼んだツール | バージョンの答え | |
|---|---|---|
| 最初の MCP 実行（複合質問） |
docdb.describe_db_clusters / describe_db_instances / describe_pending_maintenance_actions のみ |
誤り（学習知識ベース） |
| 最初の Skill 実行（複合質問） | 上記 + ドキュメント参照とみられる呼び出し | ⭕ 正しい |
| 追試（両経路、根拠を明示要求） | 両方とも verify_aws_claim |
⭕ 両方正しい |
つまり 「検証ツールを呼べば当たる、呼ばなければ学習知識で答えて外す」 という、
極めて素直な構図だった。経路は無関係。
3. 複合質問はツール選択を雑にする
最初の質問は「(1)一覧 (2)pending action (3)バージョンの新しさ」を1つのメッセージに詰め込んでいた。
エージェントは (1)(2) に必要な docdb.* API を並列で叩き、
(3)はそのついでに学習知識で答えてしまったと見える。
追試のように (3) だけを単独で、しかも「根拠を明示せよ」と条件付きで聞くと、
ちゃんと検証ツールを起動した。
4. 実務上の使い分け
以上から、回答の信頼度はプロンプトの書き方で決まる。経路選択で悩む意味はあまりない。
運用ルールとして採用したもの
-
事実確認させたい項目は「根拠（情報源・API名）も示して」と明示する。 これだけで
ドキュメント検証ツールが起動する確率が跳ね上がる - 複合質問を避ける。 特に「ついでにこれも」型の項目は学習知識で流されやすい
-
リソースの状態（pending action の有無、クラスタ構成）は API 由来なので信頼してよい。
一般知識（最新バージョン、サポート期限、推奨手順）は
aws ... describe-*や公式ドキュメントで裏取りする - 重要な判断の前には同じ質問を2回投げて突き合わせる。今回まさにそれで誤りに気付いた
なお「Skill 経由のほうが丁寧だった」（RDS の pending にも言及した）という差も、
同じくプロンプトの言い回しと実行ごとのブレの範囲で、経路の優劣ではないと考えている。
おまけ: DevOps Agent 自身も MCP を"食べる"側
API のモデルを眺めていて気付いたが、aidevops には MCPServerDetails /
DatadogServiceDetails / GrafanaServiceDetails / MCPServerNewRelicConfiguration といった
シェイプがある。これは DevOps Agent 側に外部 MCP サーバーを登録して、
エージェントの調査手段を増やすための口（RegisterService / AssociateService）。
本記事の「Claude Code から DevOps Agent を呼ぶ」とは逆方向の話だが、
Datadog や Grafana を繋いで調査範囲を広げられるのは面白い。
NewRelicを準備中なので、そのうち探して試してみたい。
まとめ
- AWS DevOps Agent には 公式のリモート MCP サーバーがある。まずこれを探すべきだった
-
SigV4 +
mcp-proxy-for-awsなら、トークン発行も有効期限管理も無しで既存の AWS プロファイルのまま繋がる -
--read-onlyはreadOnlyHintが無いせいでツールが全滅するので使えない。
permissions.denyでツール名を名指しするか、IAM 側で縛る - aws-cli に
send-messageが無いのは eventstream のため。自前実装は可能だが、機能差を考えると割に合わない - ただしスクリプト版は CI・シェルパイプ用と MCP 障害時のフォールバックとして残す価値がある
- 回答が食い違ったので追試したところ、**原因は経路ではなく「ドキュメント検証ツールを呼んだかどうか」**だった。
同一文面で聞き直すと両経路とも正答した - したがって 回答の信頼度はプロンプトの書き方で決まる。
「根拠（情報源・API名）も示して」と一言添える/複合質問を避ける/重要な判断は2回投げて突き合わせる