powered by TechFeed
表示モード
ハウツー

AIエージェントのツール実行を「read/edit/delete」の3段階で制御する — MCPツールのリスク分類とClaude Codeへの実装手法

11月16日、Nirmataが「How to classify MCP tools by risk (read, edit, delete)」と題した記事を公開した。AIエージェントが誤って本番データを上書き・削除してしまう事故は、ツール数が増えるほど現実的なリスクになる。MCPツールの権限管理を曖昧なままにしておくと、エージェントが承認なしに削除系APIを呼び出す事態を防ぐ手立てがない。本記事はそのリスクに正面から向き合い、ツールをread/edit/deleteの3クラスに分類してClaude Codeのパーミッションルールとして実装する手法を具体的に示している。

11月16日、Nirmataが「How to classify MCP tools by risk (read, edit, delete)」と題した記事を公開した。AIエージェントが誤って本番データを上書き・削除してしまう事故は、ツール数が増えるほど現実的なリスクになる。MCPツールの権限管理を曖昧なままにしておくと、エージェントが承認なしに削除系APIを呼び出す事態を防ぐ手立てがない。本記事はそのリスクに正面から向き合い、ツールをread/edit/deleteの3クラスに分類してClaude Codeのパーミッションルールとして実装する手法を具体的に示している。


MCP(Model Context Protocol)はAnthropicが策定したAIエージェント向けのツール接続仕様で、Claude Codeをはじめとするエージェントがファイル操作やAPI呼び出しなど外部ツールを利用する際の標準インターフェースとなっている。2024年末の公開以降、対応サーバーの数は急速に増えており、企業環境でも業務システムへのMCP接続が現実的な選択肢になりつつある。ツール数が増えるにつれ「どのツールを自動実行してよいか」「どこで人間の承認を挟むか」という権限管理が課題になっており、本記事はその具体的な分類手法を提示している。

3クラスの定義

各ツールを以下の3クラスに分類する。

  • Read:状態を変えない(読み取り専用)
  • Edit:状態を変えるが、追記のみ(破壊的変更なし)
  • Delete:既存データを上書き・削除しうる

MCPのToolAnnotationsスキーマはreadOnlyHintとdestructiveHintという2つのヒントを定義しており、これを軸に分類する。

クラス readOnlyHint destructiveHint
Read true 無意味(無視)
Edit false false
Delete false true

重要な落とし穴:スキーマのデフォルト値はreadOnlyHint=false、destructiveHint=trueである。つまりアノテーションを何も送らないツールは、仕様上「破壊的な書き込みを行いうるツール」として扱われる。未確認のツールはすべてDeleteクラスとして扱うのが原則だ。

ヒントは「主張」であって「保証」ではない

ここが最も重要な点だ。スキーマのコメントには明示的に次のように書かれている。

"all properties in ToolAnnotations are hints. They are not guaranteed to provide a faithful description of tool behavior"

さらに仕様はMUSTの強さで「クライアントは、信頼されたサーバー以外から受け取ったToolAnnotationsを信頼してはならない」と規定している。

つまりアノテーションだけを根拠にallow/denyルールを書いてはいけない。ヒントはレビューの手がかりであり、最終的な分類はドキュメントやコードを確認した上で人間が決定し、バージョン管理されたリストとして保持する。

ツール分類の手順

  1. tools/listリクエストでサーバーが提供するツールを列挙する
  2. 各ツールの4つのヒントをサーバーが送信した値のまま記録し、欠損しているヒントをマークする
  3. サーバーのドキュメントまたはコードでツールの実際の動作を確認する。ツール名は判断基準にならない(get_recordという名前でも書き込む場合がある)
  4. ドキュメントが許容するワーストケースのクラスを割り当てる(更新と削除の両方ができるなら、Deleteクラス)
  5. 繰り返し呼び出しが安全と確認できた場合のみidempotentHintを設定する
  6. フルツール名でリストを作成し、それを使うクライアントルールとともにバージョン管理に保存する

Claude Codeでのルール実装例

Claude Codeのパーミッションはdeny→ask→allowの順に評価され、最初にマッチしたルールが適用される。ticketsというサーバーを例にした設定は以下のとおり。

{
  "permissions": {
    "allow": [
      "mcp__tickets__get_*",
      "mcp__tickets__list_*"
    ],
    "ask": [
      "mcp__tickets__update_*"
    ],
    "deny": [
      "mcp__tickets__delete_*"
    ]
  }
}

実装上の注意点が3つある。

  • allowグロブはmcp__リテラルプレフィックスとサーバー名から始めなければならない。mcp__*のような広すぎるallowは無視され、何も承認しない
  • askはallowより先に評価されるため、サーバー全体に広いaskルールを書くとReadツールもプロンプトが出る
  • 設定ファイル内でパーミッションルールにカッコは使えない(パラメータ値による条件分岐は--disallowedToolsフラグで対応)

各シグナルの役割分担

シグナル 設定者 Claude Codeの扱い 制限
readOnlyHint サーバー read-only呼び出しを並列実行 並列化ヒントであり、パーミッションではない
destructiveHint サーバー Claude Code MCPページでは未記述 readOnlyHintがfalseの場合のみ有意
idempotentHint サーバー 新接続時に保留中の呼び出しを1度だけ再実行 繰り返しが安全な場合のみ設定
自分のクラスリスト あなた deny/ask/allowルールで強制 リストが完全な場合のみ有効

表が示すとおり、サーバー側のヒントはあくまで実行最適化のための情報であり、権限の強制力を持つのは自分で管理するクラスリストだけだ。この役割分担を理解していないと、サーバー提供のアノテーションを過信した設定になりがちなので注意が必要だ。

クラスごとの運用方針

  • Readツール:通常はallowで問題ないが、返却データのログは残す(データ漏洩リスクは残る)
  • Editツール:askルールが適切。各呼び出しで人間が確認し、承認をMCPツール呼び出しの監査ログとともに記録する
  • Deleteツール:デフォルトでdeny。特定チームに限定した明示的なルールと承認ステップを設けた場合のみ許可する

なお、クライアント側のクラス管理はサーバー側のアクセス制御を置き換えるものではない。MCPのツール仕様はサーバーが自身のツールにアクセス制御を実装することをMUSTとして要求している。クライアントとサーバーの両層で制御を重ねる「多層防御」の考え方が前提となっている。


詳細はHow to classify MCP tools by risk (read, edit, delete)を参照していただきたい。