Модуль 2 · Что такое MCP · урок 4 из 14

Три примитива: инструменты, ресурсы, промпты

Сервер может отдавать наружу три вида вещей, и главная ошибка новичка — сделать всё инструментами. В этом уроке разберём, чем примитивы отличаются не по форме, а по тому, кто решает их использовать. После него вы сможете спроектировать набор примитивов для сервера «документы проекта» — и для любого другого.

Кто контролирует примитив

Самый полезный способ различать примитивы — спросить, кто принимает решение о его использовании.

Примитив	Кто решает	Методы протокола	Пример
Инструменты (tools)	Модель	`tools/list`, `tools/call`	Прочитать документ, создать задачу
Ресурсы (resources)	Приложение (хост)	`resources/list`, `resources/templates/list`, `resources/read`	Содержимое файла, схема базы
Промпты (prompts)	Человек	`prompts/list`, `prompts/get`	«Сделай выжимку документа»

Это разделение прямо влияет на то, как примитив выглядит в интерфейсе хоста. Инструменты человек обычно не видит до момента вызова: модель решила — хост попросил подтверждение. Ресурсы хост показывает в списке, из которого пользователь выбирает, что приложить к разговору. Промпты появляются как команды через слеш или кнопки.

Инструменты: действия для модели

Инструмент — функция с типизированными входом и выходом, которую модель может вызвать сама. Сервер описывает его тремя полями: name, description и inputSchema (JSON Schema аргументов). Модель читает описание и схему и решает, когда и с какими аргументами вызвать инструмент.

Из этого следует правило: описание инструмента пишется для модели, а не для программиста. «Прочитать документ проекта целиком. Используй, когда нужен полный текст, а не выжимка» работает лучше, чем «Возвращает строку».

Инструменты могут менять мир: писать в базу, отправлять письма, удалять файлы. Поэтому протокол подчёркивает контроль человека: хосты показывают диалог подтверждения перед выполнением, позволяют заранее разрешить безопасные операции, ведут журнал вызовов. Сервер со своей стороны может сопроводить инструмент подсказками: «только читает», «разрушающий», «идемпотентный». Мы увидим их в уроке «Определяем инструменты».

В сервере «документы проекта» инструментами станут read_doc (прочитать документ по имени) и edit_doc (заменить фрагмент текста). Оба — действия, которые модель должна уметь выбирать сама по ходу задачи.

Ресурсы: данные для контекста

Ресурс — это данные, которые можно прочитать: текст документа, запись из базы, ответ API. У каждого ресурса есть URI (например, docs://brief.md) и тип содержимого (MIME-тип), чтобы хост знал, как его обрабатывать.

Ресурсы бывают двух видов:

Прямые — фиксированный URI, указывающий на конкретные данные: docs://list возвращает список документов.
Шаблоны — URI с параметрами: docs://{name} описывает целое семейство ресурсов, а docs://brief.md — один из них.

Ресурсы контролирует приложение. Хост получает список, показывает его пользователю или сам решает, что подключить: приложить целиком, найти нужный кусок поиском, предложить по контексту. Модель ресурс не «вызывает» — она получает его содержимое уже в запросе. Это важное отличие от инструментов: чтение ресурса не требует решения модели и не требует подтверждения.

Почему тогда не сделать всё инструментами, раз read_doc и ресурс docs://brief.md отдают один и тот же текст? Потому что это разные сценарии. Инструмент — когда модель по ходу задачи сама поняла, что ей нужен документ. Ресурс — когда человек заранее знает, какой документ нужен, и прикладывает его к вопросу. Хороший сервер даёт оба пути.

Промпты: шаблоны для человека

Промпт — готовый шаблон запроса с аргументами. Сервер описывает его именем, описанием и списком аргументов; хост показывает промпты пользователю, тот выбирает один, заполняет аргументы и получает готовые сообщения, с которых начинается разговор с моделью.

Промпты контролирует человек: они не срабатывают сами, их нужно явно выбрать. В Claude Code промпты сервера появляются как команды вида /mcp__имя-сервера__имя-промпта, в других хостах — в палитре команд или кнопками.

Зачем они нужны, если можно просто написать запрос руками? Автор сервера знает, как правильно пользоваться его инструментами, а пользователь — нет. Промпт «Сделай выжимку документа» может внутри содержать инструкцию «прочитай документ инструментом read_doc, выпиши только факты, не больше пяти предложений». Пользователь набирает /summarize brief.md и получает предсказуемый результат, вместо того чтобы каждый раз подбирать формулировку.

В нашем сервере будет два промпта: summarize (выжимка документа) и to_theses (переписать документ в тезисы для заданной аудитории).

Что клиент даёт серверу

Примитивы, о которых мы говорили, выставляет сервер. Но и клиент может кое-что предложить серверу. Главное из этого — элиситация (elicitation): сервер во время выполнения инструмента просит у пользователя недостающие данные или подтверждение, а хост показывает форму. Например, инструмент «создать релиз» может спросить версию, если её не передали.

В спецификации были ещё два клиентских примитива: sampling (сервер просит модель хоста что-то сгенерировать) и roots (хост сообщает серверу, в каких папках работать). В версии протокола 2026-07-28 оба помечены устаревшими, но встречаются в существующих серверах, поэтому курс «MCP: продвинутые темы» разбирает их отдельно.

Как спроектировать набор примитивов

Практичный порядок для нового сервера:

Выпишите действия, которые модель должна уметь делать сама по ходу задачи. Это инструменты. Для каждого — одно действие, понятное имя, описание для модели.
Выпишите данные, которые человек захочет приложить к разговору заранее. Это ресурсы. Если данные параметризованы («документ по имени»), это шаблон.
Выпишите типовые задачи, которые люди будут просить снова и снова. Это промпты. Внутри — инструкции, как пользоваться инструментами из пункта 1.

Проверка на здравый смысл: если у сервера десять инструментов и ноль ресурсов, скорее всего часть инструментов «прочитать X» стоит переделать в ресурсы. Если ноль промптов — пользователям придётся самим угадывать, как правильно просить.

Попробуйте сами

10–15 мин на рабочем месте

Возьмите сервис из своей работы (трекер, вики, дизайн-система, CI) и разложите его возможности по трём колонкам: инструменты, ресурсы, промпты. Для каждого инструмента напишите описание так, как его прочитает модель.
Для одного из ресурсов придумайте URI-шаблон с параметром и два конкретных URI по этому шаблону.
Напишите текст одного промпта целиком: с аргументами и инструкцией, какие инструменты использовать.

Коротко

Три примитива различаются тем, кто решает их использовать: инструменты — модель, ресурсы — приложение, промпты — человек.
Инструмент: имя, описание для модели, JSON Schema аргументов. Хост спрашивает подтверждение перед вызовом.
Ресурс: URI и MIME-тип; бывают прямые и шаблоны с параметрами. Модель ресурс не вызывает — получает готовым.
Промпт: шаблон с аргументами, который пользователь выбирает явно; внутри — инструкции, как пользоваться инструментами.
Клиент тоже может кое-что предложить серверу, главное — элиситация (запрос данных у пользователя).

Видеоверсия

Сценарий озвучки · 471 слово, ≈ 4 мин

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

Инструменты контролирует модель. Это функции с типизированными аргументами, которые модель вызывает сама, когда решит, что это нужно. Сервер описывает инструмент именем, описанием и схемой аргументов. Отсюда правило: описание пишется для модели, а не для программиста. «Прочитать документ целиком, используй, когда нужен полный текст» работает лучше, чем «возвращает строку». Инструменты могут менять мир — писать в базу, удалять файлы, — поэтому хосты показывают подтверждение перед вызовом.

Ресурсы контролирует приложение. Ресурс — это данные, которые можно прочитать: документ, запись из базы, ответ API. У него есть адрес и тип содержимого. Ресурсы бывают прямые, с фиксированным адресом, и шаблоны с параметром — например, «документ по имени». Модель ресурс не вызывает. Хост показывает список, человек или само приложение решает, что приложить к разговору, и текст попадает в запрос уже готовым. Никакого решения модели, никакого подтверждения.

Зачем тогда и инструмент «прочитать документ», и ресурс с тем же текстом? Потому что это разные сценарии. Инструмент — когда модель по ходу задачи сама поняла, что ей нужен документ. Ресурс — когда человек заранее знает, какой документ нужен, и прикладывает его к вопросу. Хороший сервер даёт оба пути.

Промпты контролирует человек. Это готовые шаблоны запросов с аргументами. Хост показывает их как команды через слеш или кнопки, пользователь выбирает, заполняет аргументы — и получает готовое начало разговора. Смысл в том, что автор сервера знает, как правильно пользоваться его инструментами, а пользователь — нет. Промпт «сделай выжимку» внутри может говорить: прочитай документ таким-то инструментом, выпиши только факты, не больше пяти предложений. Пользователь набирает короткую команду и получает предсказуемый результат.

Есть и обратная сторона: кое-что клиент даёт серверу. Главное — элиситация: сервер во время работы просит у пользователя недостающие данные или подтверждение, а хост показывает форму. Ещё два клиентских примитива, sampling и roots, в актуальной версии протокола помечены устаревшими, но встречаются в старых серверах — им посвящён продвинутый курс.

Как спроектировать набор примитивов для своего сервера? Сначала выпишите действия, которые модель должна делать сама, — это инструменты. Потом данные, которые человек захочет приложить заранее, — это ресурсы. Потом типовые задачи, которые будут просить снова и снова, — это промпты. И проверка на здравый смысл: если инструментов десять, а ресурсов ноль, часть инструментов «прочитать что-то» стоит переделать в ресурсы.

Ещё одно практическое замечание. У инструмента, ресурса и промпта разная цена для пользователя. Вызов инструмента — это решение модели, подтверждение человека и отдельный шаг. Чтение ресурса — просто вставка текста. Промпт — одна команда. Когда сомневаетесь, какой примитив выбрать, спросите себя, сколько раз в день человек будет этим пользоваться и сколько кликов вы ему сэкономите.

В нашем учебном сервере будет два инструмента — прочитать и отредактировать документ, два ресурса — список документов и содержимое по имени, и два промпта — выжимка и тезисы. В следующем уроке посмотрим, как хосты вроде Claude Code подключают такие серверы и что при этом видит пользователь.

Отметка хранится только в вашем браузере