Перевод HTTP-сервера MCP на 2026-07-28 с сохранением поддержки старых клиентов

Цель

По состоянию на 25 октября 2026 года. Перевести HTTP-сервер MCP на редакцию 2026-07-28, сохранив явно заявленную поддержку клиентов 2025-11-25. Перед развёртыванием заново проверьте спецификацию транспорта и схемы сообщений для нужной редакции, а также документированную поддержку в выбранном SDK. Здесь предлагается процедура приёмки, а не отчёт о проверенной миграции.

Предварительные условия

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

Шаги

1. Разделите обработку разных редакций протокола. Правила совместимости допускают оба варианта поведения на одной конечной точке. Старый initialize выбирает прежнюю семантику; метаданные в каждом запросе нового протокола выбирают обработку без сохранения состояния. Сохраняйте согласованное поведение старой редакции, пока поддерживаются её клиенты. Не распространяйте новые требования к заголовкам на все случаи инициализации по старому протоколу.

2. Сделайте запросы самодостаточными. Требуйте наличия io.modelcontextprotocol/protocolVersion и io.modelcontextprotocol/clientCapabilities в params._meta. Включайте сведения о клиенте, как рекомендовано, но никогда не используйте эти сообщённые самим клиентом сведения для авторизации. Прекратите получать сведения о возможностях или контекст приложения из предыдущего соединения. Предоставьте явные идентификаторы состояния, сохраняемого между вызовами.

3. Реализуйте обнаружение и проверку транспорта. Реализуйте server/discover, дублируйте версию в MCP-Protocol-Version и сверяйте обязательные заголовки с телом запроса. Базовая проверка обнаружения для тестовой конечной точки без аутентификации:

   curl --request POST 'https://mcp.example.com/mcp' \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json, text/event-stream' \
     --header 'MCP-Protocol-Version: 2026-07-28' \
     --header 'Mcp-Method: server/discover' \
     --data '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"migration-check","version":"local"}}}}'
   

   Замените URL из примера. Для защищённых конечных точек используйте одобренный для этого развёртывания тестовый клиент с аутентификацией; не отключайте аутентификацию ради проверки.

4. Обновите результаты и взаимодействия. Для обычных результатов возвращайте resultType: "complete". Реализуйте MRTR для разрешённых интерактивных операций: возвращайте input_required, затем принимайте соответствующие inputResponses и неизменённый непрозрачный requestState в запросе с новым идентификатором. Проверяйте целостность состояния, если оно влияет на права доступа или бизнес-логику; согласно рекомендациям привязывайте его к субъекту доступа, сроку действия и исходной операции. Где необходимо, обеспечивайте на сервере однократное использование.

5. Перенесите уведомления и кэширование. Замените отдельный поток уведомлений GET на subscriptions/listen. Сохраните SSE в рамках отдельных запросов там, где он используется, но уберите возобновление через Last-Event-ID: закрытие потока ответа означает отмену. Добавьте неотрицательный ttlMs и подходящий cacheScope к завершённым результатам, на которые распространяется спецификация кэширования. Исключите из кэширования промежуточные результаты и результаты повторных запросов MRTR.

6. Целенаправленно проверьте восстановление при несовместимости версий. Для неподдерживаемой версии нового протокола возвращается UnsupportedProtocolVersionError со списком поддерживаемых версий. Клиентам следует повторить запрос с совместимой версией. При HTTP 400 проверяйте тело JSON-RPC: распознанные ошибки нового протокола требуют исправления запроса или выбора версии; пустое или нераспознанное тело допускает переход к инициализации по старому протоколу. Не переходите на старый протокол лишь потому, что корректный запрос нового протокола был отклонён.

7. Проверьте прохождение через внешнюю границу развёртывания. В тестовой среде выполните через шлюз обнаружение, получение списка, безвредный вызов, повторный интерактивный запрос и подписку. Повторите проверки со старым клиентом и распределите запросы нового протокола между экземплярами. Прервите безвредный SSE-ответ и проверьте отмену и безопасное восстановление работы без возобновления потока. Проверьте авторизацию для каждой учётной записи и убедитесь, что метаданные запроса доходят до сервера без изменений.

Ожидаемый результат

Обе поддерживаемые редакции успешно выполняют свои рабочие сценарии. Операциям нового протокола не нужна транспортная сессия; старые клиенты сохраняют согласованный жизненный цикл. Держите прежнюю конфигурацию доступной до успешного прохождения приёмочных проверок.

Ограничения и основание проверки

Указанная спецификация определяет поведение протокола; приведённые шаги — предлагаемый оператором план проверки. Они не подтверждают совместимость SDK, безопасность повторного выполнения бизнес-операций или успешную работу на каком-либо конкретном балансировщике нагрузки. Для этого нужны испытания в условиях конкретного развёртывания.