MCP stateless-транспорт: как перейти на один запрос без поломки подключений

Как MCP обращается к API сервера и что меняется в stateless-режиме?

Когда я впервые полез в mcp server api, цепочка выглядела так:

1. Claude Code или другой MCP-клиент формирует сообщение.
2. Сообщение уходит на endpoint сервера, например /mcp.
3. Сервер находит метод и инструмент.
4. Результат возвращается клиенту.

В старой модели первым был служебный обмен:

клиент -> initialize
сервер -> MCP-Session-Id
клиент -> tools/call + MCP-Session-Id
сервер -> результат

Идентификатор связывал последующие запросы с одной сессией. Если сервер его выдал, клиент обязан был передавать идентификатор дальше. Сервер мог вернуть 400, если обязательного идентификатора не было. При завершённой сессии он мог отвечать 404, после чего клиент начинал новую.

Новая модель убирает этот обязательный стартовый обмен. Запрос сразу содержит нужный контекст:

POST /mcp HTTP/1.1
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: search
Content-Type: application/json

Тело запроса сообщает, какой метод вызвать, какой инструмент выбрать и какие данные передать:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "q": "otters"
    },
    "_meta": {
      "io.modelcontextprotocol/clientInfo": {
        "name": "my-app",
        "version": "1.0"
      }
    }
  }
}

Сервер при этом может помнить данные приложения. Корзина, пользователь или история могут храниться отдельно, если приложение само передаёт нужный идентификатор. Исчезает именно транспортная сессия, которая раньше связывала HTTP-запросы между собой.

Зачем переходить на stateless-транспорт?

Раньше один вызов инструмента через mcp server api требовал 2 HTTP-запроса:

1. сначала клиент инициализировал сессию;
2. потом отправлял вызов инструмента с идентификатором этой сессии.

В stateless-варианте остаётся один POST. В нём уже есть версия протокола, имя метода, имя инструмента и сведения о клиенте.

Для маленького локального сервера разница кажется незначительной. Там один процесс и один пользователь. Но даже в таком сценарии исчезает отдельная точка, на которой часто ломается первое подключение. Я видел это десятки раз в чатах и тикетах: человек правит .mcp.json, перезапускает Claude Code, клиент ждёт session ID, сервер его не выдаёт, а дальше стороны уже не понимают друг друга.

Для нескольких экземпляров польза заметнее. Любой запрос можно отправить на любой экземпляр через обычный round-robin load balancer. Не требуется привязывать конкретного клиента к конкретной машине и держать транспортное состояние в общем хранилище.

При этом stateless не означает «новый режим всегда лучше». Он хорошо подходит для независимых коротких вызовов. Если инструмент должен остановиться и ждать ответа человека, модели или события прогресса, границы начинаются сразу.

Как работает MCP session ID при stateless-транспорте?

Я проверял это на старых сборках: в спецификации 2025-11-25 сессия была необязательной. Сервер мог назначить её во время инициализации. Если сервер назначил идентификатор, клиент должен был передавать его дальше.

Старый маршрут выглядел так:

POST /mcp
method: initialize

ответ:
MCP-Session-Id: abc123

следующий POST:
MCP-Session-Id: abc123
method: tools/call

У сессионной модели были дополнительные правила:

1. сервер мог вернуть 400, если обязательный идентификатор отсутствовал;
2. сервер мог завершить сессию;
3. после завершения сервер должен был отвечать 404;
4. получив 404, клиент должен был начать новую сессию;
5. клиент мог отправить DELETE с Mcp-Session-Id, чтобы завершить сессию.

В stateless core версии 2026-07-28 этого обмена нет. Каждый запрос самодостаточен. Его можно отправить на другую реплику, потому что транспорт не требует памяти о предыдущем POST.

Разница между режимами выглядит так:

На этом месте я бы не менял конфиг вслепую. Проверь три вещи:

1. какую версию протокола понимает клиент;
2. какую версию ожидает сервер;
3. действительно ли endpoint работает в stateless-режиме.

Если клиент ждёт ответ от initialize, а сервер уже ожидает самостоятельный POST с Mcp-Method, удаление одного заголовка не поможет. Это разные схемы обмена.

Как работает HTTP MCP без хранения состояния?

Для нового маршрута тебе достаточно держать в голове четыре элемента:

• endpoint /mcp;
• HTTP POST;
• заголовок версии протокола;
• JSON-RPC-тело с методом и параметрами.

Пример вызова инструмента:

POST /mcp HTTP/1.1
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: search
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "q": "otters"
    },
    "_meta": {
      "io.modelcontextprotocol/clientInfo": {
        "name": "my-app",
        "version": "1.0"
      }
    }
  }
}

MCP-Protocol-Version нужен, чтобы сервер понимал, по каким правилам разбирать запрос. Если сервер получает неподдерживаемую версию, он должен вернуть 400 Bad Request.

Mcp-Method дублирует метод на уровне HTTP-заголовка. В примере это tools/call. Mcp-Name указывает имя инструмента, здесь search.

_meta находится внутри params. В нём новая модель передаёт identity клиента и его capabilities. Это не транспортная сессия и не скрытая замена Mcp-Session-Id: данные отправляются заново в каждом самостоятельном запросе.

Я встречал три канала: stdio, HTTP и старый SSE. stdio нужен, когда клиент запускает сервер как локальный subprocess: сервер читает JSON-RPC из stdin, а ответы пишет в stdout. В HTTP-сценарии сервер живёт отдельным процессом и принимает запросы по endpoint.

SSE не стоит путать с новым Streamable HTTP. Старый /sse встречается в инструкциях для прежнего транспорта. Для stateless-маршрута нужен endpoint вроде /mcp, который принимает POST.

В stateless-режиме сервер не держит transport state между запросами. Поэтому ему не нужен sticky session и не требуется общий storage только для идентификаторов MCP-сессий. Состояние самого приложения, если оно нужно, передаётся и хранится отдельным механизмом.

Статeless-транспорт проще всего проверять на коротком tools/list или обычном tools/call. Для подписок, прогресса и долгой операции одного POST может быть недостаточно: этим сценариям нужна stateful-механика.

На практикуме по вайб-кодингу эта связка разбирается руками: как дать агенту понятную границу задачи, как подключить внешний инструмент и как принять результат командой вместо фразы «вроде работает». Связь с MCP здесь прямая: меньше магии в конфиге, больше проверяемых действий.

Как подключить MCP-клиента к серверу?

1. Подготовь Python-сервер.

   Создай файл stateless_server.py в проекте и установи Python вместе с MCP SDK.

   Точная команда установки зависит от выбранной версии Python и SDK, поэтому я не подставляю непроверенный номер пакета или команду.

   В файл положи минимальный сервер с одним инструментом:

   python

   Скопировать

   from mcp.server.mcpserver import MCPServer
   
   mcp = MCPServer("StatelessServer")
   
   @mcp.tool()
   def greet(name: str = "World") -> str:
       """Greet someone by name."""
       return f"Hello, {name}!"
   
   if __name__ == "__main__":
       mcp.run(
           transport="streamable-http",
           stateless_http=True,
           json_response=True,
           host="127.0.0.1",
           port=3001,
       )

   stateless_http=True включает режим без транспортной сессии. json_response=True возвращает обычный JSON вместо SSE-потока. Сервер публикует локальный endpoint:

   Скопировать

   http://127.0.0.1:3001/mcp

2. Запусти сервер из проекта.

   Выполни команду из корня каталога, где лежит файл:

   bash

   Скопировать

   uv run stateless_server.py

   В примере SDK запуск файла из репозитория выглядит так:

   bash

   Скопировать

   uv run examples/snippets/servers/streamable_config.py

   Не закрывай этот процесс во время проверки. Claude Code и mcp-explorer должны обращаться к уже запущенному endpoint.

3. Проверь endpoint через CLI.

   Установи или запусти mcp-explorer, затем запроси список инструментов:

   bash

   Скопировать

   uvx mcp-explorer list http://127.0.0.1:3001/mcp

   В ответе должен появиться инструмент greet. Важен реальный обмен клиента с MCP endpoint, а не наличие Python-файла.

   Для подробного осмотра инструмента используй:

   bash

   Скопировать

   uvx mcp-explorer inspect \
     http://127.0.0.1:3001/mcp \
     greet

   Вызвать инструмент можно с таким аргументом:

   bash

   Скопировать

   uvx mcp-explorer call \
     http://127.0.0.1:3001/mcp \
     greet \
     -a name "Ada"

   mcp-explorer использует stateless-протокол по умолчанию. Для старого initialize-handshake у него есть отдельный режим --legacy. В этой статье его не включай: он проверяет другую схему подключения.

4. Создай конфигурацию проекта.

   В корне проекта создай файл .mcp.json (так же, как при подключении первого MCP-инструмента) рядом с каталогом .claude, если он есть. Не клади его внутрь .claude/.

   json

   Скопировать

   {
     "mcpServers": {
       "local-stateless": {
         "type": "http",
         "url": "http://127.0.0.1:3001/mcp"
       }
     }
   }

   Поле type укажи явно. Для HTTP Claude Code принимает http. Допустим и alias streamable-http, но для первого подключения я бы оставил короткий http.

5. Запусти Claude Code из корня.

   Перейди в тот же каталог, где лежит .mcp.json, и запусти Claude Code:

   bash

   Скопировать

   claude

   Затем открой встроенную проверку MCP:

   Скопировать

   /mcp

   Ищи сервер local-stateless и статус connected. Если Claude Code просит разрешить инструмент, подтверди greet.

6. Проверь конкретный инструмент.

   Попроси Claude Code вызвать greet с коротким аргументом, например именем Ada. Успешная проверка состоит из трёх признаков: сервер виден в списке, инструмент виден среди доступных, вызов возвращает результат Hello, Ada!.

   Сохранённый JSON-файл сам по себе успех не подтверждает. Конфигурация может читаться, а credentials, endpoint или разрешение tool могут быть неправильными.

7. Сохрани рабочую контрольную точку.

   Оставь минимальный сервер с одним инструментом до первой успешной проверки. Не добавляй сразу OAuth, несколько серверов, сложные permissions и старый /sse. Когда greet стабильно отвечает, меняй по одной вещи и снова проверяй list и call.

Как выглядит конфигурация MCP в Claude Code?

Для локального сервера достаточно такого файла:

{
  "mcpServers": {
    "local-stateless": {
      "type": "http",
      "url": "http://127.0.0.1:3001/mcp"
    }
  }
}

Удалённый endpoint с авторизацией выглядит так:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_TOKEN}"
      }
    }
  }
}

Переменная ${MCP_TOKEN} подставляется при чтении конфигурации. Сам токен не нужно вписывать в .mcp.json.

Можно использовать alias:

{
  "mcpServers": {
    "api-server": {
      "type": "streamable-http",
      "url": "https://example.com/mcp"
    }
  }
}

Но type нельзя пропускать. Если в записи есть только url, Claude Code трактует сервер как stdio и пытается запустить URL как локальную команду.

headers предназначен для HTTP-аутентификации. В конфигурации также есть поля oauth, timeout, alwaysLoad и headersHelper. Последний вариант нужен для динамического получения заголовков: helper должен вывести JSON-объект со строковыми парами ключ-значение.

Клиентская конфигурация выбирает HTTP-транспорт. Отдельного флага stateless: true в .mcp.json нет. Stateless-режим задаётся сервером и поддерживается конкретной версией клиента.

Как проверить, что MCP-сервис действительно отвечает?

Проверка через mcp-explorer:

uvx mcp-explorer list http://127.0.0.1:3001/mcp

Команда должна увидеть endpoint и показать greet.

Дальше проверь описание инструмента:

uvx mcp-explorer inspect \
  http://127.0.0.1:3001/mcp \
  greet

И выполни реальный вызов:

uvx mcp-explorer call \
  http://127.0.0.1:3001/mcp \
  greet \
  -a name "Ada"

Проверка через Claude Code начинается с CLI:

claude mcp list

Для одного сервера запроси подробности:

claude mcp get local-stateless

После запуска Claude Code открой:

/mcp

Проверь статус и список разрешённых инструментов. Если сервер подключён, но tool заблокирован approval-настройкой, сам endpoint может отвечать, а Claude не сможет вызвать функцию.

Для новой stateless-модели не нужно ожидать ручной команды initialize в пользовательском маршруте. Проверка должна доходить до самостоятельного POST и вызова инструмента. У mcp-explorer stateless-режим включён по умолчанию, а --legacy принудительно включает старый handshake.

Признаки успешного подключения:

• mcp-explorer list показывает инструмент;
• inspect возвращает описание и аргументы;
• call возвращает результат;
• claude mcp list показывает сервер;
• /mcp показывает connected;
• Claude Code видит конкретный tool;
• вызов tool завершается ответом вместо статуса failed.

Признаки частичного успеха тоже полезны. Если list работает, а call падает, endpoint уже найден, но проблема может быть в аргументах, разрешении инструмента или реализации самого handler. Если не работает даже list, сначала проверяй URL, процесс сервера и транспорт.

Как диагностировать MCP-подключения, если всё сломалось?

1. Проверь текущий scope. Сервер project scope виден только в конкретном проекте. Если запустить Claude Code из другого каталога, список может оказаться пустым.

   Конфигурация проектного сервера хранится в .mcp.json в корне. Для общего user scope Claude Code использует ~/.claude.json.

   bash

   Скопировать

   claude mcp list

   Запускай команду из корня нужного проекта. Не делай вывод по результату, полученному из домашнего каталога или другого репозитория.

2. Проверь расположение файла. Правильный путь выглядит так:

   Скопировать

   project-root/
     .mcp.json
     .claude/
       settings.json

   Файл .claude/.mcp.json может не загрузиться или загрузиться частично. Project-scoped MCP-конфигурация должна лежать в корне проекта.

3. Проверь поле type. В HTTP-записи должны быть оба поля:

   json

   Скопировать

   {
     "type": "http",
     "url": "https://example.com/mcp"
   }

   Запись только с URL ошибочна:

   json

   Скопировать

   {
     "url": "https://example.com/mcp"
   }

   Без type Claude Code воспринимает сервер как stdio.

4. Проверь endpoint. Для нового Streamable HTTP нужен путь /mcp, а старый /sse и корень / для этого маршрута не подходят.

   Скопировать

   правильный адрес: https://example.com/mcp
   старый маршрут:   https://example.com/sse

   Если сервер запущен локально, используй:

   Скопировать

   http://127.0.0.1:3001/mcp

5. Проверь OAuth отдельно. claude mcp add сохраняет конфигурацию без проверки credentials. Сервер может появиться в списке, но остаться в состоянии failed.

   Открой Claude Code и выполни:

   Скопировать

   /mcp

   Заверши browser login flow и проверь статус connected. Если сервер требует фиксированный callback port, настрой его отдельно:

   bash

   Скопировать

   claude mcp add \
     --transport http \
     --callback-port 8080 \
     my-server \
     https://example.com/mcp

6. Проверь разрешение инструмента. Статус сервера и доступность конкретного tool не одно и то же. В /mcp проверь approval, затем повтори вызов через mcp-explorer call или из Claude Code.

7. Сверь транспорт клиента и сервера. Старый клиент может ждать initialize и Mcp-Session-Id, а новый сервер может ожидать stateless POST с Mcp-Method. В такой ситуации нельзя лечить проблему удалением одного заголовка. Нужна совместимая версия клиента, сервера или переходный gateway.

Что ломается при переходе на stateless MCP?

Я проверял совместимость на нескольких сборках и вот что увидел: разница между версиями принципиальная:

клиент 2025-11-25 -> initialize -> Mcp-Session-Id
сервер 2026-07-28 -> самостоятельный POST -> stateless core

Старый клиент может ждать ответ на initialize. Новый сервер не обязан строить старую сессию. В обратную сторону новый клиент может отправлять заголовки и тело, которых старый сервер не ожидает.

Arcade.dev объясняет: клиент версии 2025-11-25 ожидает инициализацию и session ID, поэтому не может общаться с сервером версии 2026-07-28.

• Arcade.dev, MCP Going Stateless, июль 2026

На переходный период есть два рабочих направления:

• поддерживать две версии протокола;
• поставить gateway, который переводит один формат в другой.

Первый вариант требует заметной работы и усложняет поддержку. Второй добавляет промежуточный компонент, зато клиент и сервер могут временно жить на разных схемах.

Я проверяю совместимость до миграции по шести пунктам:

1. версия MCP-клиента;
2. версия сервера;
3. ожидается ли initialize;
4. используется ли Mcp-Session-Id;
5. принимает ли сервер самостоятельные POST;
6. поддерживает ли клиент MCP-Protocol-Version и новую структуру запроса.

Не делай вывод по одному факту, что URL открывается в браузере. Открытая страница не доказывает, что endpoint принимает нужный MCP POST.

Когда stateless-транспорт не подходит?

Граница проходит по жизненному циклу операции, а не по размеру JSON.

На моих тестовых серверах stateless-транспорт хорошо ложится на такой сценарий:

POST -> вызвать инструмент -> получить результат

Например:

• получить список tools;
• вызвать поиск;
• передать аргументы;
• получить короткий ответ;
• завершить запрос.

Сложнее становится, когда серверу нужно продолжить работу после паузы. AWS перечисляет несколько таких случаев:

• elicitation, когда сервер запрашивает данные у пользователя;
• sampling, когда сервер просит модель сгенерировать содержимое через клиента;
• progress notification, когда нужно передавать поток обновлений;
• длительная многошаговая операция.

Перед stateless-миграцией задай один вопрос: может ли каждый запрос завершиться независимо от предыдущего?

Если да, stateless подходит как базовый транспорт. Если нет, проверь:

1. где хранится состояние операции;
2. как сервер узнает, к какому процессу относится новый запрос;
3. как клиент получает промежуточные события;
4. как передаётся ответ пользователя;
5. поддерживают ли это SDK и конкретный клиент.

Не пытайся лечить долгий поток добавлением случайного Mcp-Session-Id. Если новая модель его не использует, нужно найти поддержанный механизм состояния, а не восстановить старый handshake вручную.

Вопросы и ответы