Cloudflare Agents SDK 0.20.0 переводит MCP-серверы на stateless-архитектуру

Cloudflare выпустила Agents SDK 0.20.0 с клиентской и серверной поддержкой кандидата в спецификацию MCP 2026-07-28. Workers теперь могут обслуживать инструменты, промпты, ресурсы и запросы пользовательского ввода без транспортной сессии и обязательного Durable Object. При этом SDK автоматически распознаёт прежние MCP-серверы и переключается на совместимый протокол.

Agents SDK 0.20.0 переносит MCP на обычную HTTP-модель

Удалённому MCP-серверу больше не требуется закреплять клиента за конкретным экземпляром приложения. В новой схеме каждый запрос содержит сведения, нужные для обработки, поэтому балансировщик может отправить его любому доступному Worker. Для команд, которые запускают несколько экземпляров сервиса, исчезает часть инфраструктуры вокруг sticky sessions и общего хранилища сессий.

Cloudflare опубликовала Agents SDK 0.20.0 27 июля 2026 года. Релиз поддерживает кандидат в спецификацию Model Context Protocol с датой 2026-07-28. MCP связывает ИИ-приложения с внешними инструментами и данными: через него агент может вызвать поиск, прочитать ресурс, получить шаблон запроса или попросить пользователя подтвердить действие.

Раньше клиент начинал работу с команд initialize и initialized, а сервер выдавал идентификатор Mcp-Session-Id. Последующие обращения зависели от этой сессии. Новая редакция протокола передаёт версию, возможности клиента и служебные данные внутри самих запросов.

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

Один маршрут обслуживает новые и прежние MCP-клиенты

Резкий разрыв совместимости мог бы превратить обновление протокола в долгую миграцию. Cloudflare выбрала автоматическое согласование: клиентский менеджер сначала вызывает server/discover и проверяет поддержку MCP 2026-07-28. Если сервер отвечает по прежней схеме, SDK продолжает соединение через старый initialize.

Существующие вызовы addMcpServer не требуют ручного указания версии протокола. Разработчику не приходится создавать два клиента или заранее знать, какую редакцию MCP поддерживает удалённый сервис. Один Agent может подключаться к новым stateless-серверам и к уже работающим системам на MCP SDK v1.

На серверной стороне действует похожий принцип. Один обработчик createMcpHandler принимает запросы нового протокола и прежних клиентов, использующих stateless-обращения. Обычные инструменты, промпты и ресурсы можно оставить на одном маршруте и с одним набором определений.

Совместимость имеет границы. Серверы с RPC, транспортными сессиями, отдельными SSE-потоками, повторным воспроизведением событий или отправляемыми сервером запросами сохраняют временную ветку на SDK v1. Cloudflare предлагает запустить новый маршрут рядом со старым, перевести состояние в явные параметры и удалить legacy-ветку после завершения активных сессий.

createMcpHandler становится основой stateless-сервера

В Agents SDK 0.20.0 функция createMcpHandler принимает фабрику, которая создаёт изолированный экземпляр McpServer для каждого запроса. Сервер импортируется из пакета @modelcontextprotocol/server, а отдельная точка входа agents/mcp/server исключает из сборки McpAgent, WorkerTransport, клиентские транспорты и модули SDK v1.

Базовая структура Worker выглядит так:

import { McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler } from "agents/mcp/server";

function createServer() {
  return new McpServer({
    name: "example",
    version: "1.0.0",
  });
}

export default {
  fetch(request, env, ctx) {
    return createMcpHandler(createServer)(request, env, ctx);
  },
} satisfies ExportedHandler;

В реальном проекте внутри createServer() регистрируются инструменты, ресурсы и промпты. Изоляция экземпляра на каждый запрос соответствует stateless-модели: обработчик получает всё нужное из текущего обращения и не рассчитывает на сохранённую транспортную сессию.

Руководство по миграции Cloudflare на момент выпуска указывает точные beta-версии пакетов:

npm i agents @modelcontextprotocol/server@2.0.0-beta.5 zod

Клиентам нужен @modelcontextprotocol/client@2.0.0-beta.5. Точная фиксация версии здесь существенна: MCP SDK v2 пока распространяется как beta, и Cloudflare предупреждает, что номер зависимости будет меняться в следующих выпусках Agents SDK.

Запросы подтверждения продолжаются без постоянного соединения

Одна из сложных задач stateless-протокола — запросить у человека дополнительные данные посреди операции. Представим агента, который собирается удалить три файла и должен получить подтверждение. Постоянного канала между сервером и клиентом уже нет, поэтому MCP использует многошаговый обмен Multi Round-Trip Requests.

Сервер возвращает результат input_required с описанием нужного поля и состоянием операции. Клиент показывает форму, собирает ответ и повторяет исходный вызов вместе с введёнными данными. Agents SDK удерживает исходные callTool, getPrompt или readResource до завершения этого цикла, а затем отдаёт приложению конечный результат.

Для пользователя это выглядит как обычный вопрос внутри интерфейса агента. Для разработчика меняется транспортная механика: подтверждение больше не зависит от открытого SSE-соединения и может продолжиться на другом экземпляре Worker.

OAuth и Origin-проверки учитывают stateless-соединения

Переход на новый транспорт затрагивает авторизацию. Agents SDK теперь проверяет сведения об издателе OAuth через SDK v2 и связывает сохранённые учётные данные с конкретным issuer. Состояние обнаружения сервера переживает перенаправления браузера и гибернацию Durable Object.

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

Обработчик Workers проверяет браузерный заголовок Origin, отклоняет повреждённые и неприменимые значения и разрешает localhost, соответствующий домен workers.dev и явно заданный CORS-домен. Для собственного домена с wildcard CORS разработчику придётся настроить allowedHostnames и allowedOriginHostnames либо передать проверку доверенному промежуточному слою.

Запросы от небраузерных MCP-клиентов без Origin остаются допустимыми. Это разделяет браузерный сценарий, где источник запроса нужно контролировать, и серверные подключения, где такой заголовок обычно отсутствует.

McpAgent переходит в режим замороженной совместимости

Версия 0.20.0 объявляет McpAgent устаревшим и замораживает его функциональность. Дата удаления пока не названа, но новые MCP-серверы Cloudflare предлагает строить через фабрику SDK v2 и createMcpHandler из agents/mcp/server.

Перегрузка createMcpHandler, принимающая сервер SDK v1, запланирована к удалению в следующей основной версии. createLegacyMcpHandler сохраняется как временный мост для проектов, которым ещё нужны транспортные сессии, повтор событий или отдельные потоки.

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

В релиз вошло ещё одно изменение для компактных MCP-проектов: @cloudflare/codemode стал необязательной peer-зависимостью. Приложения, использующие только MCP, больше не получают Code Mode транзитивно; пакет устанавливается отдельно для agents/skills и agents/browser.

Cloudflare подготовила SDK к крупнейшей переработке MCP

Обновление Agents SDK до версии 0.20.0 облегчает переход на MCP, запланированный на 28 июля 2026 года. Новые серверы теперь обрабатывают запросы без состояния, используют обычную HTTP-балансировку и получают изолированный экземпляр сервера для каждого запроса. Существующие клиенты продолжают подключаться через автоматический fallback, а проекты с сессионными функциями временно могут поддерживать два маршрута.

На момент подготовки материала Cloudflare прямо называет поддерживаемую редакцию release candidate. Проект MCP планировал финальную публикацию спецификации на 28 июля 2026 года, поэтому разработчикам стоит сверять точные версии beta-пакетов с актуальным руководством перед обновлением.

Архитектура удалённых MCP-серверов всё больше напоминает традиционные stateless HTTP API. В ближайшие недели станет ясно, насколько быстро серверы и клиенты от различных производителей адаптируются к новой модели, не использующей долгоживущие транспортные сессии.