Skip to content

Resources

Documentation Index

完全なドキュメント索引を取得してください: modelcontextprotocol.io/llms.txt

さらに先へ進む前に、利用可能なすべてのページを把握するために、このファイルを使用してください。

The Model Context Protocol (MCP) は、server が resource を client に公開するための標準化された方法を提供します。Resource により、server は file、database schema、アプリケーション固有の情報など、language model に context を与えるデータを共有できます。各 resource は URI によって一意に識別されます。

User Interaction Model

MCP における Resource は application-driven になるよう設計されており、host application が自らの要件に応じて、どのように context を取り込むかを決定します。

たとえば、アプリケーションは次のようなことができます。

  • 明示的に選択できるよう、tree view や list view の UI 要素を通じて resource を公開する
  • 利用可能な resource をユーザーが検索・絞り込みできるようにする
  • heuristic や AI model の選択に基づいて、自動的に context を含める

ただし、実装は自身の要件に合う任意のインターフェイスパターンで resource を公開して構いません。プロトコル自体は、特定のユーザーインタラクションモデルを義務付けていません。

Capabilities

resource をサポートする server は、resources capability を宣言しなければなりません (MUST)。

{
  "capabilities": {
    "resources": {
      "subscribe": true,
      "listChanged": true
    }
  }
}

この capability は 2 つの任意機能をサポートします。

  • subscribe: 個々の resource の変更通知を client が購読できるかどうか
  • listChanged: 利用可能な resource の一覧が変わったときに server が notification を送るかどうか

subscribe と listChanged はどちらも任意です。server は、どちらもサポートしないことも、片方だけ、または両方をサポートすることもできます。

{
  "capabilities": {
    "resources": {} // Neither feature supported
  }
}

{
  "capabilities": {
    "resources": {
      "subscribe": true // Only subscriptions supported
    }
  }
}

{
  "capabilities": {
    "resources": {
      "listChanged": true // Only list change notifications supported
    }
  }
}

Protocol Messages

Listing Resources

利用可能な resource を見つけるために、client は resources/list request を送信します。この操作は pagination をサポートします。

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/list",
  "params": {
    "cursor": "optional-cursor-value"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resources": [
      {
        "uri": "file:///project/src/main.rs",
        "name": "main.rs",
        "title": "Rust Software Application Main File",
        "description": "Primary application entry point",
        "mimeType": "text/x-rust",
        "icons": [
          {
            "src": "https://example.com/rust-file-icon.png",
            "mimeType": "image/png",
            "sizes": ["48x48"]
          }
        ]
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}

Reading Resources

resource の内容を取得するために、client は resources/read request を送信します。

Request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "resources/read",
  "params": {
    "uri": "file:///project/src/main.rs"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "contents": [
      {
        "uri": "file:///project/src/main.rs",
        "mimeType": "text/x-rust",
        "text": "fn main() {\n    println!(\"Hello world!\");\n}"
      }
    ]
  }
}

Resource Templates

resource template により、server は URI template を使ってパラメータ化された resource を公開できます。引数は completion API を通じて自動補完できる場合があります。

Request:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resources/templates/list"
}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "resourceTemplates": [
      {
        "uriTemplate": "file:///{path}",
        "name": "Project Files",
        "title": "📁 Project Files",
        "description": "Access files in the project directory",
        "mimeType": "application/octet-stream",
        "icons": [
          {
            "src": "https://example.com/folder-icon.png",
            "mimeType": "image/png",
            "sizes": ["48x48"]
          }
        ]
      }
    ]
  }
}

List Changed Notification

利用可能な resource の一覧が変わったとき、listChanged capability を宣言している server は notification を送るべきです (SHOULD)。

{
  "jsonrpc": "2.0",
  "method": "notifications/resources/list_changed"
}

Subscriptions

このプロトコルは、resource の変更に対する任意の subscription をサポートします。client は特定の resource を購読し、その resource が変更されたときに notification を受け取れます。

Subscribe Request:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "resources/subscribe",
  "params": {
    "uri": "file:///project/src/main.rs"
  }
}

Update Notification:

{
  "jsonrpc": "2.0",
  "method": "notifications/resources/updated",
  "params": {
    "uri": "file:///project/src/main.rs"
  }
}

Message Flow

sequenceDiagram participant Client participant Server Note over Client,Server: Resource Discovery Client->>Server: resources/list Server-->>Client: List of resources Note over Client,Server: Resource Template Discovery Client->>Server: resources/templates/list Server-->>Client: List of resource templates Note over Client,Server: Resource Access Client->>Server: resources/read Server-->>Client: Resource contents Note over Client,Server: Subscriptions Client->>Server: resources/subscribe Server-->>Client: Subscription confirmed Note over Client,Server: Updates Server--)Client: notifications/resources/updated Client->>Server: resources/read Server-->>Client: Updated contents

Data Types

Resource

resource 定義には次が含まれます。

  • uri: resource の一意な識別子
  • name: resource の名前
  • title: 表示用の、人が読める任意の resource 名
  • description: 任意の説明
  • icons: ユーザーインターフェイス表示用の任意の icon 配列
  • mimeType: 任意の MIME type
  • size: 任意の byte 単位サイズ

Resource Contents

resource には text または binary data のいずれかを含められます。

Text Content

{
  "uri": "file:///example.txt",
  "mimeType": "text/plain",
  "text": "Resource content"
}

Binary Content

{
  "uri": "file:///example.png",
  "mimeType": "image/png",
  "blob": "base64-encoded-data"
}

Annotations

resource、resource template、および content block は、client に対して、その resource をどう使うか、どう表示するかのヒントを与える任意の annotation をサポートします。

  • audience: この resource の想定対象を示す配列。取り得る値は "user" と "assistant"。たとえば ["user", "assistant"] は、両方に有用な content を示します
  • priority: この resource の重要度を示す 0.0 から 1.0 の数値。1 は「最も重要」（実質的に必須）で、0 は「最も重要でない」（完全に任意）を意味します
  • lastModified: resource が最後に変更された時刻を示す ISO 8601 形式の timestamp（例: "2025-01-12T15:00:58Z"）

annotation を含む resource の例:

{
  "uri": "file:///project/README.md",
  "name": "README.md",
  "title": "Project Documentation",
  "mimeType": "text/markdown",
  "annotations": {
    "audience": ["user"],
    "priority": 0.8,
    "lastModified": "2025-01-12T15:00:58Z"
  }
}

client はこれらの annotation を使って次を行えます。

  • 想定 audience に基づいて resource を絞り込む
  • どの resource を context に含めるか優先順位を付ける
  • 更新時刻を表示したり、新しい順に並べたりする

Common URI Schemes

このプロトコルは、いくつかの標準 URI scheme を定義しています。この一覧は網羅的ではなく、実装はいつでも追加の custom URI scheme を使えます。

https://

web 上で利用可能な resource を表すために使われます。

client がその resource を web から直接取得して読み込める場合に限って、server はこの scheme を使うべきです (SHOULD)。つまり、MCP server 経由で resource を読む必要がない場合です。

それ以外の用途では、たとえ server 自身が internet 経由で resource 内容をダウンロードする場合でも、server は別の URI scheme を使うか、custom なものを定義するべきです (SHOULD)。

file://

filesystem のように振る舞う resource を識別するために使われます。ただし、その resource が実際の物理 filesystem に対応している必要はありません。

MCP server は、directory のような通常の MIME type を持たない非通常 file を表すために、inode/directory のような XDG MIME type を使って file:// resource を識別しても構いません (MAY)。

git://

Git version control integration に使われます。

Custom URI Schemes

custom URI scheme は RFC3986 に従わなければならず、上記のガイダンスも考慮しなければなりません (MUST)。

Error Handling

server は、一般的な失敗ケースに対して標準の JSON-RPC error を返すべきです (SHOULD)。

  • Resource が見つからない: -32002
  • 内部 error: -32603

error の例:

{
  "jsonrpc": "2.0",
  "id": 5,
  "error": {
    "code": -32002,
    "message": "Resource not found",
    "data": {
      "uri": "file:///nonexistent.txt"
    }
  }
}

Security Considerations

  1. server は、すべての resource URI を検証しなければならない (MUST)
  2. 機密 resource には access control を実装すべきである (SHOULD)
  3. binary data は適切に encode されていなければならない (MUST)
  4. operation の前に resource permission を確認すべきである (SHOULD)