Протокол

Протокол MCP состоит из нескольких компонентов: базового протокола (сообщения JSON-RPC), версионирования, шаблонов обмена, авторизации, возможностей сервера и клиента и служебных функций. Все реализации ДОЛЖНЫ поддерживать базовый протокол, версионирование и шаблоны обмена, а остальное МОЖНО реализовать по потребности.

Сообщения#

Все сообщения между клиентами и серверами MCP ДОЛЖНЫ соответствовать спецификации JSON-RPC 2.0. Есть три вида сообщений.

Запросы#

Запросы идут от клиента к серверу и начинают операцию.

{
  jsonrpc: "2.0";
  id: string | number;
  method: string;
  params?: { [key: string]: unknown };
}

• Запрос ДОЛЖЕН содержать идентификатор: строку или целое число.
• В отличие от базового JSON-RPC, идентификатор НЕ ДОЛЖЕН быть null.
• Идентификатор НЕ ДОЛЖЕН совпадать с идентификатором другого запроса отправителя, на который он ещё не получил ответ.

Ответы#

Успешный ответ ДОЛЖЕН содержать тот же идентификатор, что и запрос, и поле result, а в нём поле resultType.

{
  jsonrpc: "2.0";
  id: string | number;
  result: { resultType: string; [key: string]: unknown };
}

Расширения МОГУТ добавлять свои значения. Любое незнакомое клиенту значение ДОЛЖНО считаться недопустимым. Для совместимости с серверами прежних версий, которые не передают resultType, клиенты ДОЛЖНЫ считать его отсутствие значением "complete".

Ответ с ошибкой ДОЛЖЕН содержать тот же идентификатор (кроме случая, когда идентификатор не удалось прочитать из-за некорректного запроса) и поле error с целочисленным code и строкой message. Может быть поле data с любой дополнительной информацией. Коды ошибок описаны на странице «Ошибки».

Уведомления#

Уведомление — одностороннее сообщение. Получатель НЕ ДОЛЖЕН отвечать на него, а само уведомление НЕ ДОЛЖНО содержать идентификатор.

Шаблоны обмена#

Базовый протокол поддерживает три шаблона:

1. Запрос и ответ. Клиент отправляет запрос, сервер возвращает результат или ошибку.
2. Многошаговые запросы (MRTR). Серверу для завершения запроса нужны данные от клиента (запрос данных у пользователя, сэмплинг или корневые каталоги).
3. Подписка и уведомление. Клиент подписывается на поток уведомлений, которые сервер присылает по мере появления.

Подробнее: «Шаблоны обмена».

Отсутствие состояния#

MCP — протокол без состояния: вся информация, нужная для обработки запроса, содержится в самом запросе. Сервер обрабатывает каждый запрос независимо и не выводит ничего из предыдущих запросов, даже на том же соединении или потоке. В частности:

• Серверы НЕ ДОЛЖНЫ полагаться на предыдущие запросы по тому же соединению, чтобы установить контекст (возможности, версию протокола, личность клиента): каждый запрос передаёт эти данные в _meta.
• Серверам СЛЕДУЕТ быть готовыми к запросам, связанным с несколькими задачами, потоками или разговорами.
• Серверам НЕ СЛЕДУЕТ требовать, чтобы клиент использовал одно и то же соединение или процесс для связанных операций.
• Клиентам НЕ СЛЕДУЕТ использовать отдельную задачу, поток или разговор как границу времени жизни процесса stdio.
• Состояние, которое должно сохраняться между запросами (долгие задачи, дескрипторы приложения), ДОЛЖНО передаваться явным идентификатором при каждом запросе.

Открытое соединение, например процесс stdio, — не разговор и не сессия: клиенты могут чередовать несвязанные запросы на одном транспорте, а сервер не должен принимать идентичность соединения или процесса за признак непрерывности разговора. Долгие запросы вроде subscriptions/listen остаются парой «запрос — ответ»: просто ответ представляет собой открытый поток уведомлений.

Поля _meta#

Свойство _meta позволяет клиентам и серверам прикреплять к взаимодействиям дополнительные метаданные. Часть ключей зарезервирована MCP для служебных данных.

Формат имён ключей#

Имя ключа состоит из необязательного префикса и имени.

• Префикс — цепочка меток через точку, заканчивающаяся косой чертой. Метка начинается с буквы, заканчивается буквой или цифрой, внутри допустимы буквы, цифры и дефисы. Рекомендуется обратная доменная запись (com.example/).
• Префиксы, в которых вторая метка modelcontextprotocol или mcp, зарезервированы для MCP: io.modelcontextprotocol/, dev.mcp/. А com.example.mcp/ не зарезервирован: вторая метка здесь example.
• Имя, если не пусто, начинается и заканчивается буквой или цифрой, внутри допустимы дефисы, подчёркивания и точки.

Зарезервированные ключи#

Обязательные поля каждого запроса#

Запрос без обязательного поля некорректен: сервер ДОЛЖЕН отклонить его кодом JSON-RPC -32602 (неверные параметры), а в HTTP — статусом 400 Bad Request. Клиентам СЛЕДУЕТ указывать clientInfo в каждом запросе, если не настроено иначе.

Сервер НЕ ДОЛЖЕН полагаться на возможности, которые клиент не объявил. Если для запроса нужна не объявленная возможность, сервер ДОЛЖЕН вернуть MissingRequiredClientCapabilityError (-32021) с перечнем недостающих возможностей в data.requiredCapabilities (в HTTP со статусом 400).

Авторизация#

MCP определяет механизм авторизации для транспортов на основе HTTP. Реализациям на HTTP СЛЕДУЕТ ему соответствовать. Реализациям на stdio НЕ СЛЕДУЕТ его применять: учётные данные берутся из окружения. Клиенты и серверы МОГУТ согласовать собственные способы аутентификации и авторизации. Раздел «Безопасность» этого сайта готовится.

Схема#

Полное описание протокола задано схемой на TypeScript: она источник истины обо всех сообщениях и структурах. JSON Schema создаётся из неё автоматически для автоматизированных инструментов.

Схемы JSON Schema внутри сообщений#

• Если в схеме нет поля $schema, по умолчанию действует JSON Schema 2020-12. Реализации ДОЛЖНЫ поддерживать как минимум 2020-12 и СЛЕДУЕТ документировать поддержку других диалектов.
• Реализации ДОЛЖНЫ проверять схемы по заявленному или умолчательному диалекту, а неподдерживаемый диалект обрабатывать корректно, вернув ошибку.
• Реализации НЕ ДОЛЖНЫ автоматически загружать $ref, указывающие на сетевой URI. Загрузка МОЖЕТ быть включена опционально, но по умолчанию выключена, и тогда СЛЕДУЕТ использовать список разрешённых хостов, отклонять петлевые, локальные и частные адреса, ограничивать время и размер и вести журнал.
• Схемы с неразрешённым внешним $ref СЛЕДУЕТ отклонять, а не считать «разрешающими всё».
• Конструкции композиции (anyOf, oneOf, allOf, if/then/else) и $defs дороги в проверке, поэтому СЛЕДУЕТ задать ограничения (глубина схемы, число подсхем, бюджет времени), чтобы вредоносная схема не стала вектором отказа в обслуживании.

Дальше#

• Транспорты: stdio и Streamable HTTP.
• Шаблоны обмена: MRTR, подписки, отмена, прогресс.
• Ошибки: коды и их распределение.
• Версии и совместимость: согласование версий и эпохи протокола.