第2章 ツールとMCP

学習目標

  • エージェントが誤用しにくく、トークンを節約できるツールを設計し、改善効果を評価で確認します。
  • ツール結果のサイズをページネーション・フィルター・切り詰め・参照で管理します。
  • MCPのホスト・クライアント・サーバーの役割と、2026-07-28仕様のステートレスモデルを説明します。
  • プロトコルエラーとツール実行エラーを区別し、回復行動につながるエラーを設計します。
  • ツールアノテーション、認証、scopeを信頼境界に合わせて扱い、最小権限を付与します。

はじめに

新入社員に社内システムのマニュアル300ページを渡し、「必要なものは全部ここにあります」と言う場面を想像してください。情報は網羅されていても、最初の1週間は違う画面を開き、似た名前のメニューを混同し、エラーコードの前で立ち止まるでしょう。既存のAPIをそのままラップしたツールを何十個も受け取ったエージェントが経験するのも、これと同じです。

ツールは、エージェントが世界を見る窓であり、手でもあります。この章では、まず何をツールにし、名前・パラメーター・結果・エラーをどう設計するかを扱います。続いてMCPの構成と2026-07-28仕様の変更、アノテーション・認証・scopeで権限境界を引く方法を整理し、「さらに深く」ではツールが数百個に増えたときの戦略と、コードでツールを呼ぶ方式を見ていきます。

重要な概念

ツールはエージェントのためのインターフェースである

人が使う画面の設計をHCI(人間-コンピューターインターフェース)と呼ぶように、エージェントが使うツールと説明の設計を、AnthropicはACI(エージェント-コンピューターインターフェース)と呼び、HCIと同じだけ力を注ぐよう勧めています。同じ記事には、SWE-benchエージェントの作成時に、プロンプト全体よりもツールの最適化に多くの時間を使ったと記されています。

代表的な手法はポカヨケ(poka-yoke)、つまり間違えにくくする設計です。モデルがルートディレクトリから移動した後に相対パスを繰り返し間違えたため、チームはツールが常に絶対パスだけを受け付けるよう変更し、モデルは問題なく使えました。指示に「パスに注意」と書く代わりに、誤り得る入力自体をなくしたのです。SIMカードの一角を切り欠き、逆向きに挿せなくするのと同じ発想です。

確認する問いは単純です。説明とパラメーターだけで使い方が明確か、使用例と境界事例があるか、新人開発者に渡しても迷わないか。そして多くの入力で試験し、モデルがどこで間違えるかを見ます。

適切なツールを選ぶ

Anthropicの「Writing effective tools for agents」は、ツールが多ければ結果がよくなるわけではないと強調しています。よくある失敗は、APIエンドポイントを一つずつそのまま包むことです。アドレス帳なら全件を返すlist_contactsの代わりにsearch_contactsやmessage_contact、予定なら空き時間の検索から予約まで行うschedule_eventを一つ作る、といった形で、影響の大きい業務フローに合わせた少数のツールに複数段階をまとめるよう勧めています。

境界の基準は「人の担当者なら、この仕事を一度に処理するか」です。細かすぎると組み合わせの負担で呼び出しが増え、広くまとめすぎるとパラメーターが増えて誤用しやすくなります。重複するツールは統合し、似ていても用途が違うツールは名前と説明で違いを明示します。

名前、説明、パラメーター

複数サービスのツールを使う場合、名前が選択の最初の手掛かりになります。同じ記事は、サービスやリソース単位の接頭辞でまとめる名前空間を勧めています(asana_search、jira_search、asana_projects_search)。パラメーターは名前だけで意味が明確であるべきです。userよりuser_idが適切です。

説明には、ツールが行うことと行わないこと、入力形式と単位、結果の意味を書きます。「レコードを修正する」と説明され、idとvalueだけを受け取るupdateツールを次のように直すと、違いがわかります。

{
  "name": "shipment_set_weight",
  "description": "出荷前の貨物の実測重量を記録する。出荷済みの貨物は変更できない。重量はキログラムで、小数第1位まで。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "shipment_number": { "type": "string", "description": "例:SH-2026-004211" },
      "weight_kg": { "type": "number", "minimum": 0.1, "maximum": 30000 }
    },
    "required": ["shipment_number", "weight_kg"],
    "additionalProperties": false
  }
}

改善案では単位をパラメーター名に含め、許容範囲をスキーマで制限し、変更できない場合を説明に明記しました。タイムゾーンなどモデルが間違えやすい値は、ISO 8601形式とタイムゾーン表記を必須にする、UTCだけを受け付けるなど、形式によって誤りの余地をなくします。スキーマで防げない業務ルール(在庫を超えて出荷できないなど)はサーバーで検査します。形式が正しくても業務上は誤った呼び出しがあり得るためです。

意味のある結果を返す

ツール結果は、次の行動の材料です。同じ記事は、uuid、256px_image_url、mime_typeなどの低レベルの識別子より、名前などエージェントがすぐ使えるフィールドを返すよう勧めています。また、わかりにくい識別子を読める言葉に置き換えると検索精度が上がったと述べています。次の呼び出しにIDが必須なら、名前と一緒に渡せばよいのです。

応答の詳しさを選ばせる方法もあります。response_formatのような列挙型パラメーターで「concise」と「detailed」を選べるようにすれば、通常は簡潔な応答を使い、IDが必要な場合だけ詳細な応答を選べます。同記事の例では詳細版が206トークン、簡潔版が72トークンと約3分の1でした。

ツール結果のサイズ管理

大きな結果はコンテキストを占有し、第3章で扱うコンテキスト劣化(context rot)を早めます。同記事が勧める手法は、ページネーション、範囲選択、フィルタリング、妥当なデフォルト値を設けた切り詰めです。またClaude Codeはツール応答をデフォルトで25,000トークンに制限すると記しています。

手法 設計例
デフォルト件数とページ limitはデフォルト20、次ページのカーソルを返す
サーバー側フィルター 期間・状態・担当者で先に絞り込むパラメーター
フィールド選択 必要な列だけを選ぶfieldsパラメーター
切り詰めの案内 「1,240件中20件のみ表示。期間を絞るかstatusでフィルターしてください」
参照を返す 大きな成果物はファイルやリソースとして置き、場所だけを返す

切り詰める場合は、必ず切り詰めた事実と範囲を結果に記します。そうしないと、エージェントは受け取った20件が全件だと考えます。MCPツールは、後で読むURIをresource_linkとして結果に返せます。またoutputSchemaを定義すると、structuredContentで構造化結果を返します。出力スキーマがある場合、サーバーは必ずそれに適合する結果を返さなければならず(MUST)、クライアントは検証することが推奨されます(SHOULD)。後方互換性のため、同じJSONをテキストブロックにも含めることを勧めています。

エラーは回復のための指示である

MCP仕様はツールのエラーを二つに分けます。

種類 例 伝達方法 モデルの回復可能性
プロトコルエラー 未知のツール、形式が不正なリクエスト、サーバーエラー JSON-RPCのerror 低い
ツール実行エラー API失敗、入力検証失敗、業務ルール違反 結果のisError: trueと説明 高い。引数を修正して再試行

仕様は、クライアントがツール実行エラーをモデルに伝え、自ら修正できるようにすることを推奨しています(SHOULD)。実行エラーは正常な結果と同じ形で返ります。2026-07-28版のすべての結果には種類を示すresultTypeが付き、完了した結果は"complete"です。

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "resultType": "complete",
    "content": [{ "type": "text", "text": "配送日は今日以降である必要があります。今日は2026-10-20です。" }],
    "isError": true
  }
}

よいエラーメッセージは次の行動を示します。入力の修正、待ってからの再試行、追加の権限取得、人への引き継ぎを区別してください。注意すべきケースが一つあります。タイムアウトのような、実行されたか不明なエラーです。決済処理後に応答だけが失われた可能性があるため、この場合の正しい指示は「再試行」ではなく「処理結果を照会する」です。内部のスタックトレースや機密の値はエラーに含めません。

副作用のあるツール:プレビューと確定

参照ツールは誤用しても失うのはトークンだけですが、変更ツールは外部システムの状態を変えます。取り消しにくい変更には、プレビューと確定の分離が有効です。

  1. 準備ツールが変更対象、変更後の値、影響(金額、受信者、件数)を計算して返し、有効期間の短いプレビュー識別子を発行する。
  2. 人またはポリシー検査がプレビュー内容を確認する。
  3. 確定ツールはプレビュー識別子だけを受け取る。サーバーは識別子が指す内容をそのまま実行する。
  4. 同じ識別子で2回確定しても、効果は一度しか発生しないようにする(冪等性)。

この構成は、承認内容と実行内容が食い違う隙間をなくし、再試行が重複実行につながることも防ぎます。相対値(「10%上げる」)より絶対値(「1日の予算を30万ウォンにする」)を受け付けることも、同じポカヨケです。同じリクエストが2回来ても結果が変わらないからです。

MCPの構成

MCP(Model Context Protocol)は、LLMアプリケーションと外部データ・ツールをつなぐオープンなプロトコルです。メッセージはJSON-RPC 2.0形式に従い、参加者は三つです。

役割 説明
ホスト 接続を開始するLLMアプリケーション
クライアント ホスト内で一つのサーバーと通信するコネクタ
サーバー 文脈と機能を提供するサービス

サーバーは三つの機能を提供します。リソース(ユーザーやモデルが使う文脈とデータ)、プロンプト(ユーザー向けのテンプレートメッセージとワークフロー)、ツール(モデルが実行する関数)です。クライアントは、サーバーがユーザーに追加情報を求めるelicitationを提供できます。2026-07-28版はRoots、Sampling、Loggingを非推奨(Deprecated)に指定しました。当面は動きますが、新規実装では導入しないという意味です。仕様が示す代替手段は、それぞれツールのパラメーターやサーバー設定でディレクトリを渡すこと、LLMプロバイダーのAPIと直接連携すること、標準エラー出力やOpenTelemetryでログを残すことです。

仕様の安全原則によれば、ツールは任意コード実行として扱う必要があり、ホストは呼び出し前にユーザーの明示的な同意を得て、人が呼び出しを拒否できるようにすることが推奨されます(SHOULD)。

2026-07-28仕様:ステートレスとハンドル

この版の最大の変更は、MCPがステートレス(stateless)プロトコルになったことです。処理に必要な情報はすべてリクエスト内にあり、サーバーは同じ接続上の以前のリクエストから、プロトコルのバージョン・クライアント能力・身元などの文脈を引き継いではなりません(MUST NOT)。そのため、すべてのクライアントリクエストは_metaにio.modelcontextprotocol/protocolVersionとio.modelcontextprotocol/clientCapabilitiesを必ず含めます。欠けていればサーバーは不正なパラメーターのエラー(-32602)で拒否します。クライアント名とバージョン(io.modelcontextprotocol/clientInfo)も含めることを勧めていますが、自己申告値なのでセキュリティ判断には使えません。以前の版のinitializeハンドシェイクとセッションIDヘッダーは廃止され、サーバーが対応バージョンと能力を通知するserver/discoverが加わりました。起動中のstdioプロセスも、会話やセッションではありません。

複数呼び出しにまたがる状態(カート、開いたブラウザ、DBトランザクション)が必要なら、生成ツールが明示的なハンドルを返し、以降の呼び出しがそのハンドルを引数として受け取ります。仕様の非規範的な指針は次のとおりです。

  • 認証されたサーバーでは、ハンドルは名前にすぎず、権限ではありません。呼び出しごとに、呼び出し元の権限をハンドルと照合します。
  • ハンドルは内部構造を明かさない不透明な識別子とし、保持期間は生成ツールの説明に記載します。
  • 期限切れや未知のハンドルには、その事実を示すツール実行エラーを返し、モデルが新しく作れるようにします。

処理の途中で追加のユーザー入力が必要なら、複数往復リクエスト(MRTR)を使います。サーバーがresultType: "input_required"の結果に必要なリクエストと不透明なrequestStateを入れて返すと、クライアントは回答を埋め、元のリクエストを新しいIDで再送します。requestStateはクライアントを経由するため、サーバーは改変され得る入力として扱い、権限や業務ロジックに影響するなら完全性を保護しなければなりません(MUST)。elicitationにはクライアント画面の入力フォームを使うフォームモードと、ユーザーを外部ページに送るURLモードがあります。フォームモードでパスワード・APIキー・トークン・決済情報を要求してはならず、こうした情報はクライアントを経由しないURLモードで受け取ります。

注意

プロトコルがステートレスとは、サーバーが業務データや長時間タスクの状態を持たないという意味ではありません。状態は持てますが、接続ではなく明示的な識別子にひも付ける必要があるという意味です。2025-11-25までの版はinitializeハンドシェイクを使い、Streamable HTTPサーバーがセッションIDを発行する場合もあったため、まず接続相手のバージョンを確認してください。

トランスポート、キャンセル、長時間タスク

MCPの標準トランスポートは二つです。クライアントがサーバーをサブプロセスとして起動し、標準入出力で通信するstdioと、リモートサーバーとHTTPで通信するStreamable HTTPです。以前のHTTP+SSEトランスポートは非推奨です。

キャンセルとタイムアウトはトランスポートごとに異なります。Streamable HTTPでは、リクエストの応答ストリームを閉じることがキャンセルであり、サーバーはクライアントの切断時にそのリクエストをキャンセルとして扱います。2026-07-28版はストリームの再開機能を廃止したため、切断されたリクエストは新しいIDで再送する必要があります。stdioではnotifications/cancelledを送ります。仕様はすべてのリクエストにタイムアウトを設定するよう勧め、進捗通知(progress)を受けた際にタイマーをリセットすることはできても、進捗通知にかかわらず最大タイムアウトは常に強制することを推奨しています(SHOULD)。

数分、数時間かかるタスクを一つの接続に結び付けると、途中のプロキシのタイムアウトやクライアントの再起動に弱くなります。公式拡張のTasksを使うと、サーバーは結果の代わりに永続的なタスクハンドルを返します。クライアントはtasks/getで状態(working、input_required、completed、failed、cancelled)を照会し、再起動後も同じIDで継続できます。拡張を使うには、双方が対応を表明する必要があります。

ツールアノテーションと信頼

ツール定義にはname、title、description、inputSchema、outputSchema、annotationsなどが含まれます。名前は1〜128文字で、英字・数字・アンダースコア・ハイフン・ピリオドのみを使うことが推奨されます。複数サーバーのツールを集めると名前が重複し得るため、仕様はサーバー識別子の接頭辞などによる区別を勧めています。またserverInfoのサーバー名は一意とは限らないため、それに依存しないよう求めています。

アノテーション(annotations)は、ツールの動作を説明するヒントです。

アノテーション 意味 デフォルト値
readOnlyHint 環境を変更しない false
destructiveHint 破壊的な変更を行い得る(読み取り専用でない場合のみ意味を持つ) true
idempotentHint 同じ引数で繰り返しても追加の効果がない(読み取り専用でない場合のみ意味を持つ) false
openWorldHint 外部の開かれた世界(Web検索など)とやり取りできる true

デフォルト値が保守的である点に注目してください。アノテーションのないツールは、環境を変更し、破壊的であり得て、外部世界とやり取りできると想定されます。また仕様は、信頼できるサーバーからのものでなければ、クライアントはアノテーションを信頼できないものと見なさなければならない(MUST)と警告しています。アノテーションはサーバーの自己紹介であり、保証書ではありません。自動承認などの権限判断は、サーバーの信頼レベルとホストのポリシーに結び付けます。

認証と最小権限

仕様の認証範囲はトランスポートによって異なります。HTTPベースのトランスポートはMCPの認可(Authorization)仕様に従うことを推奨し(SHOULD)、stdioはこの仕様に従わず、実行環境から認証情報を取得するよう勧めています。

セキュリティのベストプラクティス文書の主要なルールは次のとおりです。

リスク ルール
トークンパススルー(token passthrough) MCPサーバーは自身に発行されていないトークンを受け取ってはならない(MUST NOT)。受け取ったトークンを下位APIへそのまま渡すと、監査証跡(audit trail)やレート制限などの制御が崩れる
混乱した代理人(confused deputy) 固定クライアントIDで第三者APIに接続するプロキシサーバーは、クライアントごとの同意を得てから第三者の認可へ進む必要がある
ハンドルの窃取 ハンドルの保有を認証として扱わない。サーバー側でハンドルを認証済みユーザーにひも付ける
過剰なscope 最小のscopeから始め、権限が必要な操作を初めて試みたときに、WWW-Authenticateのscope要求で段階的に引き上げる。*、allなどの包括的なscopeは避ける
ローカルサーバー ワンクリックインストールに対応するクライアントは、実行コマンド全体を省略せず表示し、明示的な承認を得る必要がある。最小権限のサンドボックスでの実行を勧める

scopeは、トークンが許可する操作の範囲です。マスターキーを一つ渡すより、今必要な部屋の鍵だけを渡し、必要時に追加するほうが紛失時の被害を抑えられます。tools/listは接続によって変わってはなりませんが、リクエストの認可によっては変わってよいため、サーバーは呼び出し元のscopeで許可されたツールだけを表示できます。ただし非表示は利便性のためにすぎず、実際の遮断は呼び出しごとのサーバー側権限検査が担います。

人による承認とセキュリティ要件

仕様のツールセキュリティ要件では、サーバーとクライアントの役割が異なります。

主体 要件
サーバー(MUST) すべての入力検証、適切なアクセス制御、呼び出し頻度の制限、出力のサニタイズ
クライアント(SHOULD) 機密性の高い操作前のユーザー確認、送信する入力の事前表示(意図しない漏洩の防止)、モデルへ渡す前の結果検証、タイムアウト、監査ログ

どの呼び出しに人の確認を設けるかは第5章で決めます。ここでは、確認画面に実際に送信する入力を表示すべき点だけ覚えてください。「メールを送りますか」だけの確認では、受信者が変わった呼び出しも通してしまいます。

さらに深く

ツールが数百個に増えたとき

複数のMCPサーバーを接続すると、ツール定義だけでコンテキストの相当部分を占めます。MCPのクライアント向けベストプラクティス文書は、この場合に段階的な発見(progressive discovery)を勧めています。ホストがツール定義を取得して保持しつつ、コンテキストにはすぐ入れず、軽量なsearch_toolsメタツールで必要なツールを探してから全定義を読み込む方式です。文書は、一覧(名前と一行の説明)、詳細(一つのツールの完全なスキーマ)、実行の三層を例示し、定義がコンテキストウィンドウの一定割合(例えば1〜5%)を超えたら移行するよう勧めています。検索にはキーワード、埋め込み、小さなモデルによる選択、またはそれらの組み合わせを使い、一部のモデルプロバイダーは組み込みのツール検索を提供します。

落とし穴はプロンプトキャッシュです。多くのプロバイダーはtools配列を含むプロンプトの先頭部分をキャッシュするため、会話中に定義を出し入れしたり順序を変えたりするとキャッシュが無効になります。文書は、新たに見つけた定義をキャッシュ位置の後ろに追加するか、配列を変えないよう、ツール名と引数を受け取って代理実行する固定のcall_toolメタツール一つに全呼び出しを集約するよう勧めています。仕様がtools/listを決定的な順序で返すよう推奨する理由も同じです。

モデルがコードでツールを呼ぶとき

ツールを直接呼ぶ場合、呼び出しのたびに結果全体がモデルを通ります。数千行のログを読み、エラーの種類ごとにチケットを作る仕事なら、モデルはその全行を読む必要があります。プログラムによるツール呼び出し(code mode)では、モデルがツールを呼ぶコードを書き、それをサンドボックスで実行し、最終結果だけをモデルに返します。中間データがコンテキストに入らないため、トークンとレイテンシを大きく減らせます。

一方、コード実行という新たな攻撃面が生まれます。MCP文書が挙げる条件は六つです。サンドボックスに直接のネットワークアクセスを与えず全通信をホストの仲介に通すこと、認証情報はホストが保持して生成コードに公開しないこと、スクリプトの承認を内部の全呼び出しの承認と見なさないこと、あるサーバーの結果を別のサーバーにとっては信頼できない入力として扱うこと、実行時間とメモリを制限すること、サンドボックス出力を検証・切り詰めてからモデルに渡すことです。呼び出しが1〜2回だけの対話的な仕事では複雑さが利点を上回る場合があるため、大量データを絞り込み、集約する仕事から適用してください。

ツールの変更を契約として管理する

スキーマが同じでも、説明の一行や結果フィールドの意味が変われば、エージェントの行動は変わります。そこで、名前・説明・スキーマ・業務上の意味を一つのバージョンとして管理し、変更履歴を残し、デプロイ前の評価で確認します。Anthropicは、実際の課題で実行時間・ツール呼び出し数・トークン・ツールエラーを測り、評価セットだけに適合しないよう、ホールドアウト検証セット(held-out test set)でも確認するよう勧めています。リサーチシステムの記事は、ツール説明を書き直すエージェントのおかげで、その後のタスク完了時間が40%減ったと報告しています。サーバーは一覧の変更をnotifications/tools/list_changedで通知でき、クライアントはこのときキャッシュ済みの一覧を破棄して再取得します。

実務の場面

うねりアド:予算変更ツールに安全装置を入れる

広告代理店「うねりアド」の運用エージェントは、広告プラットフォームの11個のAPIをそのまま包んだツールを使っていました。前四半期の事故は二種類でした。名前の似たキャンペーン(「秋の特価_検索」と「秋の特価_検索_再訪問」)を取り違えて運用したものが9件、タイムアウト後の再試行で「日予算を20%増額」が2回適用されたものが3件ありました。

チームは三つの案を検討しました。システムプロンプトに注意書きを増やす案は、前四半期にも実施済みのため却下しました。11個のツールを維持して説明だけを磨く案は、相対値による増額と重複実行という構造的な原因をなくせないとして却下しました。選んだのはツールの再設計です。

参照はcampaigns_find(query, status)一つに統合し、結果にキャンペーン名・ID・現在の日予算・担当者を含めました。変更は二つに分けました。budget_change_preview(campaign_id, new_daily_budget_krw)は絶対値だけを受け取り、変更前後の金額、月間の予想出稿額、有効期間10分のプレビューIDを返します。budget_change_apply(preview_id)はプレビューIDだけを受け取り、同じIDが2回来ても一度だけ適用します。従来比50%を超える増額は、isError: trueとともに「担当者の承認が必要です。承認リクエストツールを使ってください」と返します。タイムアウト時は再試行せず、プレビューIDで適用済みか照会させました。

過去の事故12件を変形した課題40件と、別に用意した新しい課題25件で評価しました。両セットとも誤ったキャンペーンの変更と重複増額は0件で、課題あたりのツール呼び出しは4.8回から2.6回に減りました。

あおぞらソフト:デプロイ用MCPサーバーの権限を引き直す

開発プラットフォーム企業「あおぞらソフト」は、エージェントがデプロイ状態を照会し、問題時にロールバックするためのリモートMCPサーバーを作りました。初版は迅速な実装を優先しました。ユーザーのCIシステムのトークンをそのまま受け取ってCI APIに渡し、scopeはdeploy:*一つだけで、デプロイIDを知っていれば誰のデプロイでもロールバックできました。

セキュリティレビューは三点を指摘しました。自身に発行されていないトークンを受け取って転送していること(トークンパススルー)、参照だけのユーザーにもロールバック権限があること(過剰なscope)、デプロイIDを権限のように使っていること(ハンドルを認証として扱うこと)です。

再設計したサーバーは、MCPの認可で自身に発行されたトークンだけを受け取り、対象(audience)を検証します。CI APIにはサーバー自身の認証情報でアクセスしますが、呼び出しのたびにユーザーのデプロイ権限を社内の権限システムに問い合わせ、下位呼び出しの監査記録に実際のユーザー識別子を残します。最初はdeploy:readだけを求め、初めてロールバックを試みるとdeploy:rollbackを要求して段階的な引き上げを促します。tools/listはscopeに応じてロールバックツールを隠しますが、呼び出し時は必ずサーバーで再検査します。ツールにはdestructiveHint: trueを付け、ホストは社内サーバーを信頼済みとして登録して、このアノテーションに基づいて確認画面を表示します。

採用しなかった案は「ツール説明に『ロールバックは慎重に』と書く」でした。説明はモデルへの推奨にすぎず、権限境界ではないからです。

間違えやすいポイント

  1. 「APIを漏れなくツールとして公開すればエージェントが自ら選ぶ」 既存APIのラッパーは素早く作れるため魅力的ですが、組み合わせの負担がモデルに移り、似たツールを混同します。業務フロー単位の少数のツールが適切です。
  2. 「エラーはプロトコルエラーとして投げるのが定石だ」 通常のAPIの慣行に沿うため自然に見えますが、モデルが修正できる業務エラーは、isErrorと具体的な説明で返してこそ自ら回復できます。
  3. 「readOnlyHintが付いているから安全だ」 仕様のフィールドなので公式の保証に見えますが、アノテーションはサーバーの自己申告です。信頼できないサーバーのアノテーションで権限を判断してはいけません。
  4. 「受け取ったトークンを下位APIにそのまま渡せば便利だ」 実装が最も簡単で魅力的ですが、仕様が禁止するトークンパススルーです。監査追跡、レート制限、信頼境界が同時に崩れます。
  5. 「結果を切り詰めればサイズの問題は終わりだ」 トークン数は減りますが、切り詰めた事実と範囲を知らせなければ、エージェントは一部を全体と信じて結論を出します。
  6. 「MCPがステートレスになったからサーバーに状態を置いてはいけない」 名前からそう聞こえますが、状態は置けます。接続ではなく明示的なハンドルにひも付け、ハンドルごとに権限を検査します。
  7. 「一覧で隠したツールは呼び出せない」 画面から消えると遮断されたように見えますが、一覧のフィルターは利便性のためです。実際に遮断するのは呼び出しごとのサーバー側権限検査です。

ひと目でわかるまとめ

  • ツールはACIです。誤り得る入力を形式で排除します(絶対パス、絶対値、単位を含む名前)。
  • エンドポイント単位ではなく業務フロー単位で少数のツールを作り、名前空間で区別します。
  • 結果は次の行動に使うフィールドで返し、詳しさはresponse_format、サイズはページ・フィルター・切り詰め案内・参照で管理します。
  • 業務エラーはisErrorと回復の指示で返します。実行の有無が不明なエラーは、再試行より照会を優先します。
  • 取り消しにくい変更はプレビューと確定に分け、冪等にします。
  • 2026-07-28のMCPはステートレスです。_metaのバージョン・能力は必須で、状態はハンドルにひも付けますが、ハンドルは権限ではありません。
  • 最大タイムアウトは進捗通知にかかわらず強制し、長いタスクはTasks拡張を検討します。
  • アノテーションのデフォルト値は保守的で、信頼できないサーバーのアノテーションは信用しません。
  • トークンパススルーは禁止です。最小scopeから段階的に引き上げ、毎回サーバー側で権限を検査します。

公式ドキュメントで確認する

セルフチェック

2-1. 人間の開発者に便利なAPIと、エージェントに適したツールが異なる理由を、コンテキストのコストと選択ミスの観点から説明してください。

2-2. 応答の詳しさを選ぶパラメーター(response_formatなど)が解決する問題と、エージェントが詳細応答を選ぶべき場合を説明してください。

2-3. ツールが結果を切り詰めて返す際、一緒に記すべき情報を二つ挙げ、それがないときのエージェントの誤りを説明してください。

2-4. 2026-07-28仕様で、サーバーが同じ接続の以前のリクエストから引き継いではならない情報を三つ挙げ、代わりにどこへ載せるか説明してください。

2-5. アノテーションが一つもないツールをクライアントがどう想定するか、仕様のデフォルト値と結び付けて説明してください。

2-6. トークンパススルーが監査追跡とレート制限を崩す理由を、それぞれ一文で説明してください。

2-7. 社内図書貸出システムの「貸出延長」をエージェント用ツールにします。誤用しにくいツール名、パラメーター(形式を含む)、業務エラー一つとそのメッセージ、人の確認が必要な条件を、それぞれ決めてください。

実習課題

実習

ツールを一つ再設計して測定する(60分)

  1. エージェントがよく使う、またはよく間違えるツールを一つ選ぶ。
  2. 実際の利用記録から課題20件を抽出し、15件を改善用、5件を検証用に分ける。
  3. 現在のツールで実行し、課題あたりのツール呼び出し数・トークン・ツールエラーを記録する。
  4. この章の原則で再設計する(業務フロー単位、単位を含むパラメーター名、デフォルト件数と切り詰め案内、回復指示のあるエラー)。
  5. 改善用と検証用の課題をすべて再実行し、三つの指標を比較する。

完了基準: 検証用課題で三指標のうち二つ以上が改善し、課題成功率が低下しなければ完了とする。改善しなければ、トランスクリプトからモデルがツールを誤解した箇所を見つけ、説明を修正した記録が必要である。

実習

権限表とサーバー側検査を作る(45分)

  1. 運用中のMCPサーバー(またはツール群)を一つ選び、すべてのツールを列挙する。
  2. 各ツールの読み取り・書き込み、取り消し可能性、必要なscope、付けるアノテーションを表にする。
  3. 最小scopeの集合(初回接続時)と、段階的な引き上げが必要なscopeを分ける。
  4. 書き込みツールを一つ選び、呼び出し元の権限を対象リソースと照合するサーバー側検査コードを書き、権限のない呼び出しへのエラーメッセージを決める。

完了基準: 権限のないユーザーの呼び出しがサーバー検査で拒否される試験が通り、表に全ツールのscopeとアノテーションが漏れなく記載されていれば完了とする。