MCPツールアノテーション——4ヒントでリスク語彙を設計する

MCPサーバーを50本以上のツールで構成するエンタープライズ環境では、どのツールがファイルを書き換え、どのツールが外部APIを呼び出し、どのツールを並列実行しても安全かをクライアントが把握できなければ、承認フローもリスク評価も成立しない。MCP仕様が定義するToolAnnotationsは、ツールの副作用特性をサーバーがクライアントに宣言するためのリスク語彙だ。

MCP（Model Context Protocol）の実装基盤についてはMCPサーバー実装ガイドを、認可設計はMCPのOAuth 2.1スコープ設計を参照してほしい。

ToolAnnotationsとは何か——「ヒント」が持つ設計上の意味

ToolAnnotationsはツールの副作用特性を4つのbooleanヒントで宣言するリスク語彙で、クライアントが承認フロー・並列実行・信頼評価を制御するための根拠を提供します。

MCP仕様（2025-06-18版）はToolsのannotationsフィールドにToolAnnotations型を定義している。仕様が明言する重要な前提が1つある——アノテーションはヒントであり保証ではない。クライアントは「信頼できるサーバーからのアノテーションのみ信頼する」と仕様に明記されており、悪意ある・誤実装のサーバーが誤ったアノテーションを返す可能性を常に考慮しなければならない。

``json { "name": "delete_records", "description": "指定条件に一致するレコードを削除する", "inputSchema": { "type": "object", "properties": { "filter": { "type": "string" } }, "required": ["filter"] }, "annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": false } }``

デフォルト値の設計思想が重要だ。アノテーションを省略したツールは「非読み取り専用・破壊的・非冪等・オープンワールド」として扱われる。最悪ケースを想定する保守的デフォルトが採用されており、アノテーションは「リスクを下げる宣言」として機能する。

4フィールドの定義と設計判断

4つのアノテーションは独立したboolean値で、デフォルトは保守的な「最悪ケース」想定です。組み合わせによってツールのリスクプロファイルが決まります。

フィールド	デフォルト	意味
`readOnlyHint`	`false`	`true`=環境を変更しない（読み取り専用）
`destructiveHint`	`true`	`true`=削除・上書き等の不可逆な変更の可能性あり
`idempotentHint`	`false`	`true`=同一引数の繰り返し呼び出しが安全
`openWorldHint`	`true`	`true`=インターネット・外部APIへの通信あり

設計上の判断ポイントを3点挙げる。

readOnlyHintとdestructiveHintの関係: destructiveHintはreadOnlyHint: falseの場合のみ意味を持つ。読み取り専用ツールにdestructiveHintを設定することは仕様上無効だ。実装時はreadOnlyHint: trueを設定したツールではdestructiveHintを省略するのが明快な設計になる。

openWorldHintの扱い: 外部APIと通信しない閉域内ツール（オンプレミスDBへの読み書きなど）ではopenWorldHint: falseを設定する。将来的に外部接続が追加される可能性がある場合はデフォルト（true）のままにするのが保守的設計だ。

idempotentHintの適用範囲: 冪等性が保証される操作（upsert・ステートレスな外部API呼び出し）のみtrueにする。「同じ結果が返る」だけでなく「副作用が重複しない」まで確認してから設定する。

クライアントによるアノテーション活用パターン

クライアントはreadOnlyHintで並列実行可否を決定し、destructiveHintで承認プロンプトを制御し、openWorldHintでコンテンツ信頼度を引き下げます。

並列実行の最適化: Claude CodeはreadOnlyHint: trueのツールを並列ディスパッチし、falseのツールは直列化して競合ミューテーションを防ぐ。MCP公式ブログ（2026年3月）によれば、読み取り専用ツールを正確にアノテートするとdispatch rateが2倍程度向上する。

承認フロー制御: destructiveHint: trueのツール呼び出しに確認プロンプトを表示し、idempotentHint: trueのツールは失敗時のリトライを自動化できる。このロジックをクライアントが実装することで、「確認なしに実行して良い操作」と「人間の承認が必要な操作」を宣言的に分離できる。

信頼境界フラグ: openWorldHint: trueのツールが返すコンテンツは、プロンプトインジェクション攻撃の侵入口になり得る。外部WebページをスクレイピングするツールがLLMのコンテキストに取り込まれた悪意ある指示を実行させるシナリオは、openWorldHintが正しく設定されていれば事前にフラグを立てることができる。

「危険な三つ組み」と多層防御

プライベートデータアクセス・外部通信・外部コンテンツ取得の三つが同一セッションに揃うと、アノテーションだけでは防御できない高リスク状態になります。

エンタープライズMCPデプロイで特に注意すべき構成パターンが「lethal trifecta（危険な三つ組み）」だ。

プライベートデータアクセス: 社内CRM・従業員DBへの書き込みツール（readOnlyHint: false）
外部通信: Slack送信・外部メールAPIへの投稿ツール（openWorldHint: true・readOnlyHint: false）
外部コンテンツ取得: 外部URLスクレイピング・未審査ドキュメント取得（openWorldHint: true）

この三つが1セッションに共存すると、外部コンテンツにプロンプトインジェクションが仕込まれた場合、エージェントが社内データを外部に送信するシナリオが成立する。ToolAnnotationsはこのリスクパターンを検出・可視化するための語彙を提供するが、それ自体は攻撃を防止しない。

多層防御の設計では、アノテーションに加えてネットワーク層のエグレスフィルタリング（承認済み外部エンドポイントのみ許可）と実行環境のサンドボックス（外部コンテンツ処理を隔離したコンテナ・MicroVM）を組み合わせる。アノテーションはあくまで「クライアントへの意図の宣言」であり、インフラレベルの制御と補完関係にある。

エンタープライズ規模のMCPサーバー管理・アノテーション設計ガイドライン策定・多層防御アーキテクチャの実装についてはKuuのRDEサービスが支援している。

参考

まとめ

MCPのToolAnnotationsはreadOnlyHint・destructiveHint・idempotentHint・openWorldHintの4フィールドで構成されるリスク語彙だ。デフォルトはすべて最悪ケースを想定する保守的設計であり、アノテーションは「リスクを下げる宣言」として機能する。

クライアントはアノテーションを並列実行の最適化・承認フロー制御・信頼境界フラグとして活用するが、アノテーション自体は保証ではなくヒントに過ぎない。エンタープライズ環境では「危険な三つ組み」パターンを認識したうえで、ネットワーク層のエグレスフィルタリングとサンドボックス実行環境をアノテーションと組み合わせた多層防御を設計することが重要だ。

MCPサーバーのアノテーション設計・エンタープライズ向けセキュリティアーキテクチャのご相談はKuuのRDEサービスまでお問い合わせください。