Ресурсы и шаблоны ресурсов в MCP

Ресурс (resource) в Model Context Protocol (MCP) - данные, которые сервер предоставляет клиенту для использования в качестве контекста: содержимое файла, схема базы данных, документ, запись приложения. Каждый ресурс идентифицируется URI. Шаблон ресурса (resource template) описывает целое семейство ресурсов шаблоном URI, например weather://forecast/{city}/{date}, чтобы клиент мог построить URI нужного ресурса.

Ресурсы входят в MCP с первой опубликованной версии спецификации, 2024-11-05. Версия 2026-07-28 изменила то, как клиент узнаёт об изменениях ресурсов: метод resources/subscribe заменён общим потоком subscriptions/listen. Та же версия добавила подсказки для кеширования и сменила код ошибки для отсутствующего ресурса. Статья соответствует текущей версии, 2026-07-28. Базовые понятия протокола описаны в статье Что такое MCP.

Кратко

Какую задачу решают ресурсы

Модель отвечает точнее, когда у неё есть нужный контекст: обсуждаемый файл, схема базы данных, документация API. Без протокола каждое ИИ-приложение получает такие данные по-своему. Ресурс даёт этим данным единый адрес и единый способ чтения с любого сервера.

Спецификация называет ресурсы управляемыми приложением (application-driven). Хост решает, какие ресурсы и как включить в контекст. По спецификации приложение может показывать ресурсы деревом или списком для выбора пользователем, предлагать поиск и фильтры или включать контекст автоматически, по эвристикам или по выбору модели. Ни один из этих интерфейсов протокол не предписывает.

Документация описывает ресурсы как пассивные источники данных с доступом только на чтение. Этим они отличаются от инструментов, которые выполняют действия и которые выбирает модель. Различия сведены в конце статьи; инструменты описаны в статье Инструменты (tools) в MCP.

История

В таблице - изменения ресурсов по версиям спецификации.

URI и схемы

У каждого ресурса есть URI в смысле RFC 3986. URI может использовать любую схему, а как её толковать, решает сервер. Спецификация описывает несколько распространённых схем и оговаривает, что список не исчерпывающий.

Для схемы https:// есть ограничение. Серверу следует использовать её, только если клиент может сам загрузить ресурс из веба. Если содержимое загружает из интернета сам сервер, ему всё равно следует выбрать другую схему или определить собственную.

Для ресурсов file:// сервер может указывать тип MIME из спецификации XDG, например inode/directory, для объектов без стандартного типа MIME, таких как каталоги.

Собственные схемы встречаются часто. Документация MCP приводит примеры вроде calendar://events/2024 и travel://activities/{city}/{category}. Расширение MCP Apps использует схему ui:// для ресурсов с интерактивными интерфейсами; расширения описаны в статье Расширения MCP.

Определение ресурса

Сервер описывает каждый ресурс объектом. В таблице - его поля по схеме 2026-07-28.

По схеме хост может использовать size, чтобы показывать размер файлов и оценивать, какую часть контекстного окна займёт ресурс.

Получение списка ресурсов

Клиент запрашивает список ресурсов методом resources/list. Метод поддерживает постраничную выдачу: если в результате есть nextCursor, клиент передаёт это значение в cursor и получает следующую страницу.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/list",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": { "name": "example-client", "version": "1.0.0" },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "complete",
    "resources": [
      {
        "uri": "file:///project/README.md",
        "name": "README.md",
        "title": "Project Documentation",
        "mimeType": "text/markdown",
        "size": 4120,
        "annotations": {
          "audience": ["user", "assistant"],
          "priority": 0.8,
          "lastModified": "2026-10-30T09:12:00Z"
        }
      }
    ],
    "nextCursor": "page-2",
    "ttlMs": 300000,
    "cacheScope": "private"
  }
}

Правила для списка те же, что и для инструментов. В списке - ресурсы, которые сейчас доступны запрашивающему клиенту; он может быть пустым и может меняться со временем. Список не должен зависеть от соединения или меняться как побочный эффект других запросов, но может зависеть от авторизации запроса, например от прав (scopes) токена.

Чтение ресурса

Клиент читает ресурс методом resources/read и передаёт его URI:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "resources/read",
  "params": {
    "uri": "file:///project/src/main.rs",
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": { "name": "example-client", "version": "1.0.0" },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

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

Результат - массив contents. На один запрос сервер может вернуть несколько элементов: например, содержимое нескольких файлов при чтении ресурса-каталога.

По Streamable HTTP запрос несёт заголовки Mcp-Method: resources/read и Mcp-Name с URI ресурса, чтобы шлюзы могли маршрутизировать запросы, не разбирая тело. Транспорты описаны в статье Транспорты MCP.

Сервер также может ответить на resources/read результатом типа input_required, если перед чтением ресурса ему нужны дополнительные данные. Тогда клиент повторяет запрос с ответами в inputResponses. Этот механизм описан в статье MCP без состояния.

Текстовое и двоичное содержимое

Каждый элемент contents содержит URI, необязательный mimeType и данные в одной из двух форм. Текстовое содержимое передаётся в поле text, которое заполняется, только если данные действительно представимы текстом. Двоичное содержимое передаётся в поле blob в кодировке Base64:

{
  "uri": "file:///project/docs/architecture.png",
  "mimeType": "image/png",
  "blob": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="
}

Тип MIME позволяет клиенту правильно обработать данные. Спецификация требует, чтобы двоичные данные были корректно закодированы.

Ошибки

Если запрошенного ресурса нет, сервер обязан вернуть ошибку JSON-RPC с кодом -32602 (Invalid params). Для внутренних ошибок ему следует возвращать -32603.

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

До версии 2025-11-25 включительно отсутствующий ресурс обозначался кодом -32002. Этот код остаётся зарезервированным, и клиентам следует по-прежнему принимать его от серверов прежних версий.

Сервер не должен возвращать пустой массив contents для несуществующего ресурса. Пустой массив неоднозначен: он может означать, что ресурс существует, но содержимого у него нет.

Шаблоны ресурсов

Шаблон ресурса описывает параметризованные ресурсы шаблоном URI по RFC 6570. Клиент запрашивает шаблоны методом resources/templates/list, который, как и другие списки, поддерживает постраничную выдачу и кеширование:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "resultType": "complete",
    "resourceTemplates": [
      {
        "uriTemplate": "weather://forecast/{city}/{date}",
        "name": "weather-forecast",
        "title": "Weather Forecast",
        "description": "Weather forecast for any city and date",
        "mimeType": "application/json"
      }
    ],
    "ttlMs": 3600000,
    "cacheScope": "public"
  }
}

У шаблона есть поля uriTemplate, name, title, description, mimeType, annotations, icons и _meta. Поле mimeType указывается, только если у всех ресурсов, подходящих под шаблон, один и тот же тип.

Документация различает два способа обнаружения. Прямые ресурсы (direct resources) имеют фиксированные URI и попадают в resources/list, например calendar://events/2024. Шаблоны описывают динамические URI с параметрами, например travel://activities/{city}/{category}. Клиент подставляет значения в шаблон, получает URI вида travel://activities/barcelona/museums и читает его методом resources/read.

Автодополнение аргументов шаблона

Сервер может подсказывать значения параметров шаблона, пока пользователь их вводит. Сервер с такой поддержкой объявляет возможность completions. Клиент отправляет completion/complete со ссылкой типа ref/resource, шаблоном URI, именем аргумента и его текущим значением:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "completion/complete",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": { "name": "example-client", "version": "1.0.0" },
      "io.modelcontextprotocol/clientCapabilities": {}
    },
    "ref": { "type": "ref/resource", "uri": "weather://forecast/{city}/{date}" },
    "argument": { "name": "city", "value": "Par" }
  }
}

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "resultType": "complete",
    "completion": { "values": ["Paris", "Park City"], "total": 2, "hasMore": false }
  }
}

Ответ содержит не больше 100 значений, отсортированных по релевантности, необязательное поле total и признак hasMore. Для шаблонов с несколькими параметрами клиент передаёт уже выбранные значения в context.arguments. Тот же механизм обслуживает аргументы промптов, которые описаны в статье Промпты (prompts) в MCP.

Аннотации

Ресурсы, шаблоны ресурсов и блоки содержимого поддерживают необязательные аннотации. Это подсказки, которые помогают клиенту решить, как использовать или показывать данные.

По спецификации клиент может использовать аннотации, чтобы отбирать ресурсы по адресату, решать, какие ресурсы включить в контекст, и сортировать их по свежести. Как именно хост должен реагировать на конкретные значения, спецификация не определяет.

Ресурсы в результатах инструментов

Инструмент может вернуть ресурсы в результате двумя способами. В таблице они сравниваются.

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "resultType": "complete",
    "content": [
      {
        "type": "resource_link",
        "uri": "file:///project/src/main.rs",
        "name": "main.rs",
        "description": "Primary application entry point",
        "mimeType": "text/x-rust"
      },
      {
        "type": "resource",
        "resource": {
          "uri": "file:///project/Cargo.toml",
          "mimeType": "text/plain",
          "text": "[package]\nname = \"demo\"\nversion = \"0.1.0\""
        },
        "annotations": { "audience": ["assistant"], "priority": 0.7 }
      }
    ]
  }
}

Обе формы поддерживают те же аннотации, что и ресурсы. Встроенные ресурсы могут быть и в сообщениях промптов; по схеме клиент сам решает, как показать их модели или пользователю. Результаты инструментов описаны в статье Инструменты (tools) в MCP.

Уведомления об изменениях и подписки

В возможности resources сервер объявляет две необязательные функции:

• listChanged: сервер отправляет notifications/resources/list_changed, когда меняется список ресурсов;
• subscribe: сервер отправляет notifications/resources/updated, когда меняется ресурс, за которым следит клиент.

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

С версии 2026-07-28 оба вида уведомлений приходят только в поток, который клиент открывает запросом subscriptions/listen. Этот запрос заменил прежние методы resources/subscribe и resources/unsubscribe и отдельную точку HTTP GET. Клиент перечисляет нужные типы уведомлений; другие типы сервер отправлять не должен.

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "subscriptions/listen",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": { "name": "example-client", "version": "1.0.0" },
      "io.modelcontextprotocol/clientCapabilities": {}
    },
    "notifications": {
      "resourcesListChanged": true,
      "resourceSubscriptions": ["file:///project/config.json"]
    }
  }
}

Сначала сервер отправляет notifications/subscriptions/acknowledged с той частью фильтра, которую согласился выполнять; неподдерживаемые типы в ней отсутствуют. Клиенту следует сравнить её с запрошенным. Дальше сервер присылает уведомления по мере изменения ресурсов:

{
  "jsonrpc": "2.0",
  "method": "notifications/resources/updated",
  "params": {
    "_meta": { "io.modelcontextprotocol/subscriptionId": 8 },
    "uri": "file:///project/config.json"
  }
}

Каждое сообщение в потоке несёт io.modelcontextprotocol/subscriptionId, равный id запроса subscriptions/listen в JSON-RPC. У клиента может быть несколько подписок одновременно, и он различает их по этому полю. URI в уведомлении может указывать на вложенный ресурс того, на который подписан клиент. Нового содержимого уведомление не несёт: клиент заново читает ресурс методом resources/read.

Подписка заканчивается, когда клиент закрывает поток SSE (Streamable HTTP) или отправляет notifications/cancelled (stdio), когда её завершает сервер или когда закрывается транспорт. Серверу, который завершает подписку по своей инициативе, следует сначала отправить обычный ответ на запрос subscriptions/listen. Если транспорт закрылся без такого ответа, это неожиданный разрыв, после которого клиент может переподключиться. На stdio сервер не хранит состояние подписок между переподключениями, поэтому клиент отправляет subscriptions/listen заново.

Кеширование

Окончательные результаты resources/list, resources/templates/list и resources/read обязаны нести подсказки для кеширования. ttlMs - время в миллисекундах, в течение которого результат можно считать актуальным; cacheScope определяет, кто может использовать его повторно. Поля описаны в статье Инструменты (tools) в MCP; несколько правил касаются именно ресурсов.

• Ключ кеша - метод вместе с параметрами, которые влияют на результат. Для resources/read это uri.
• private подходит для результатов resources/read, которые зависят от аутентифицированного пользователя. public подходит для данных, одинаковых для всех пользователей.
• Результат, полученный повторным запросом с inputResponses или requestState, кешировать нельзя.
• Соответствующее уведомление, например notifications/resources/list_changed для закешированного списка, сразу делает закешированный результат устаревшим, даже если TTL ещё не истёк.

Сервер может изменить данные и до истечения TTL: TTL - подсказка об актуальности, а не гарантия. Спецификация также требует, чтобы сервер применял контроль доступа к каждому примитиву и не полагался только на cacheScope.

Безопасность

Спецификация предъявляет требования к серверам, которые предоставляют ресурсы:

• сервер обязан проверять все URI ресурсов;
• для чувствительных ресурсов следует реализовать контроль доступа и проверять права перед операциями;
• двоичные данные обязаны быть корректно закодированы;
• для ресурсов file:// сервер обязан очищать пути, чтобы не допустить выхода за пределы каталога (directory traversal).

Содержимое ресурса попадает в контекст модели. Текст документов, веб-страниц или задач может содержать инструкции, адресованные модели; этот риск описан в статьях Безопасность MCP и Prompt injection.

Ресурс и инструмент

Ресурсы и инструменты могут дать модели доступ к одним и тем же данным, но работают по-разному. В таблице они сравниваются.

Главное различие - кто инициирует доступ. Ресурс выбирает приложение или пользователь, и он добавляется в контекст. Хост решает, что передать модели: часть данных, результаты поиска или всё целиком. Инструмент выбирает модель по ходу диалога и сама заполняет его аргументы.

Два примитива используются вместе. Инструмент может вернуть ссылку на ресурс, и клиент прочитает ресурс, когда понадобятся данные. В MCP Apps инструмент ссылается в своём _meta на ресурс ui:// с интерфейсом, и хост может прочитать этот ресурс ещё до вызова. Промпт может объединить ресурсы и инструменты в одном сценарии; промпты описаны в статье Промпты (prompts) в MCP.

Термины

Источники

• Resources, specification 2026-07-28(откроется в новой вкладке) (на английском)
• Schema of the specification 2026-07-28 (schema.ts), GitHub(откроется в новой вкладке) (на английском)
• Subscriptions, specification 2026-07-28(откроется в новой вкладке) (на английском)
• Caching, specification 2026-07-28(откроется в новой вкладке) (на английском)
• Completion, specification 2026-07-28(откроется в новой вкладке) (на английском)
• Tools, specification 2026-07-28(откроется в новой вкладке) (на английском)
• Streamable HTTP, specification 2026-07-28(откроется в новой вкладке) (на английском)
• Overview: error codes, specification 2026-07-28(откроется в новой вкладке) (на английском)
• Key changes, specification 2026-07-28(откроется в новой вкладке) (на английском)
• Key changes, specification 2025-11-25(откроется в новой вкладке) (на английском)
• Key changes, specification 2025-06-18(откроется в новой вкладке) (на английском)
• Key changes, specification 2025-03-26(откроется в новой вкладке) (на английском)
• Resources, specification 2024-11-05(откроется в новой вкладке) (на английском)
• Understanding MCP servers, MCP documentation(откроется в новой вкладке) (на английском)
• MCP Apps, MCP documentation(откроется в новой вкладке) (на английском)