MCPのResource LinkとURI Templateを使い分ける｜大きな結果を本文へ埋め込まない設計

必要な情報だけあとから読む：MCP Resource LinkとURI Template MCP・コンテキスト設計
カテゴリー
MCP・コンテキスト設計
公開日
2026.09.10

はじめに

MCP Toolが長いログや文書全文を毎回返すと、通信量だけでなくモデルへ渡すコンテキストも増えます。結果を「どこにあるか」と「必要ならどう読むか」に分ける仕組みがResourceです。

この記事は、MCPのToolとJSONの基本を知り、文書や検索結果の返し方を設計したい方が対象です。Resourceは取得対象のデータ、URIはそのデータを指定する識別子と考えてください。JSON例を比較し、全文を返す場合と参照だけを返す場合を選べることを目指します。サーバーを一から構築する手順ではなく、既存のMCP接続で使うメッセージと設計の解説です。

この記事では次の3つを整理します。

  • Resource：固定URIで読める既知のデータ
  • Resource Template：引数入りURIのパターン
  • Resource Link：Tool結果からResourceを指すリンク

固定Resource

クライアントはresources/listで候補を取得し、resources/readで本文を読みます。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/read",
  "params": { "uri": "docs://project/readme" }
}

応答はcontents配列です。

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "contents": [{
      "uri": "docs://project/readme",
      "mimeType": "text/markdown",
      "text": "# Project\n..."
    }]
  }
}

URIは識別子であり、必ずしもブラウザから直接fetchできるURLではありません。独自schemeの意味と認可はサーバーが定義します。

Resource Template

記事IDごとにResourceを一覧へ何千件も並べる代わりに、テンプレートを公開できます。

{
  "uriTemplate": "docs://articles/{id}",
  "name": "article",
  "title": "記事本文",
  "description": "IDで記事本文を取得します",
  "mimeType": "text/markdown"
}

テンプレートはresources/templates/listで発見します。{id}を展開したdocs://articles/42をresources/readへ渡します。ユーザー入力をそのままファイルパスへ連結せず、ID形式の検証、認可、存在確認を行います。

Tool結果のResource Link

検索Toolが全文ではなく候補を返す例です。

{
  "content": [{
    "type": "resource_link",
    "uri": "docs://articles/42",
    "name": "article-42",
    "title": "キャッシュ設計ガイド",
    "description": "検索語に一致した記事",
    "mimeType": "text/markdown"
  }]
}

クライアントは候補を利用者へ示し、必要なものだけ読みます。Toolが返したResource Linkは、resources/listにも必ず出るとは限りません。リンクを受け取ったクライアントは、そのURIを直接resources/readできる設計かを確認します。

埋め込みResourceとの違い

Tool結果にはResource本文を埋め込む形式もあります。

{
  "type": "resource",
  "resource": {
    "uri": "docs://articles/42/summary",
    "mimeType": "text/plain",
    "text": "この記事はキャッシュ無効化を説明します。"
  }
}

小さく、呼出結果と同時に必要な要約は埋め込みが便利です。長い本文、画像、更新されるログはResource Linkにし、必要時に取得する方が扱いやすくなります。

annotationsを使う

{
  "audience": ["user", "assistant"],
  "priority": 0.8,
  "lastModified": "2026-08-31T12:00:00Z"
}

annotationsはクライアントへのヒントであり、アクセス制御ではありません。priority: 1でも必ずモデルへ入る保証はなく、audienceだけで秘密を守ることもできません。認可はResourceの読取時にサーバーで実施します。

設計チェックリスト

  • URIは安定し、利用者の秘密を含まない
  • MIME typeと文字コードを正しく返す
  • sizeを示せる場合は生データのバイト数として扱う
  • テンプレート引数を検証する
  • listに出ないリンクもreadできるか仕様化する
  • 存在しないURIと権限不足を区別しすぎて情報漏えいしない
  • 大きなbinaryはbase64増加を見込む
  • 更新通知・購読はクライアント能力を確認して使う

動作確認

  1. resources/templates/listにテンプレートが出る
  2. 正しいIDで本文を読める
  3. 不正ID、存在しないID、権限のないIDを拒否する
  4. ToolのResource Linkから同じURIを読める
  5. 本文をTool応答へ重複して埋め込んでいない
  6. ページネーションのnextCursorをクライアントが処理する

トラブル対処

  • Linkを読めない：Tool結果のURIがresources/readへ登録され、同じ認可規則を通るか確認します。
  • Templateが一致しない：展開結果とサーバー側のURI正規化を比較します。
  • コンテキストが大きい：本文を埋め込まず、選択後に必要なResourceだけ読みます。

まとめ

MCP Resourceはデータ、TemplateはURIの規則、Resource Linkは別途読めるデータへの参照です。小さな要約だけをTool結果へ置き、大きな本文を必要時に読む設計にすると、コンテキストと通信量を制御しやすくなります。

参考リンク

タイトルとURLをコピーしました