Транспортные механизмы MCP

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

Транспорт	Значение type	Где запущен сервер	Лучше всего для
stdio	"stdio" (по умолчанию при наличии command)	Локальный процесс на вашей машине	Локальные инструменты, расширения IDE
SSE	"sse"	Удалённый HTTP сервер	Старые размещённые серверы
Streamable HTTP	"http" или "streamableHttp"	Удалённый HTTP сервер	Новые размещённые серверы (рекомендуется)

Транспорт stdio

stdio запускает команду на вашей машине как дочерний процесс. Kodik записывает JSON-RPC сообщения в stdin процесса и читает ответы из его stdout. Stderr процесса захватывается отдельно для журналирования ошибок.

Как это работает

Kodik                         Серверный процесс
  |                                 |
  |--- JSON-RPC (stdin) ----------->|
  |                                 | (обрабатывает запрос)
  |<-- JSON-RPC (stdout) -----------|
  |                                 |

Характеристики

• Только локально — бинарный файл сервера должен быть установлен на вашей машине
• Наименьшая задержка — без участия сетевого стека
• Один-к-одному — каждый экземпляр Kodik получает собственный серверный процесс
• Изначально безопасен — нет сетевой доступности

Поля конфигурации

{
  "servers": {
    "my-local-server": {
      // type: "stdio" выводится автоматически при наличии command
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": { "API_KEY": "..." },
      "cwd": "/optional/working/dir",
    },
  },
}

Когда использовать stdio

• Инструменты, которым нужен прямой доступ к локальной файловой системе или процессам
• Серверы, установленные через npm, pip или uv
• Сценарии с одним пользователем
• Операции, где важна задержка

Транспорт SSE

SSE (Server-Sent Events) подключается к удалённому HTTP серверу. Kodik открывает постоянное GET соединение, через которое сервер отправляет события, и отправляет запросы серверу через HTTP POST на отдельный эндпоинт. Kodik использует переподключающийся EventSource, чтобы кратковременные сбои сети не прерывали поток.

Как это работает

Kodik                              Удалённый сервер
  |                                      |
  |--- HTTP GET /sse ------------------->| (установить поток)
  |<--- SSE поток событий ---------------| (постоянный)
  |                                      |
  |--- HTTP POST /message -------------->| (запрос клиента)
  |<--- SSE событие с ответом -----------| (ответ)

Характеристики

• Удалённый — сервер работает где угодно в сети
• Многоклиентский — один экземпляр сервера может обслуживать многих клиентов
• Авто-переподключение — Kodik переподключается автоматически при прерывании сети
• Требует явного type: "sse" — нужно установить для отличия от streamable HTTP при наличии поля url

Поля конфигурации

{
  "servers": {
    "my-sse-server": {
      "type": "sse",
      "url": "https://example.com/mcp/sse",
      "headers": { "Authorization": "Bearer token" },
    },
  },
}

Когда использовать SSE

• Серверы, созданные до того, как streamable HTTP стал стандартом
• Сервисы, которые явно документируют SSE эндпоинт

Транспорт Streamable HTTP

Streamable HTTP — современный транспорт MCP, представленный в спецификации MCP как преемник SSE. Он использует единый HTTP эндпоинт, который может передавать ответы потоком. Используйте type: "http" (Kodik также принимает "streamableHttp" и нормализует оба к одной внутренней реализации).

Как это работает

Kodik отправляет запросы на URL и получает потоковые ответы через то же соединение. Токены OAuth bearer прикрепляются автоматически, если настроена аутентификация.

Характеристики

• Удалённый — сервер работает где угодно в сети
• Современный — рекомендуется для всех новых реализаций серверов
• Более простая серверная реализация, чем SSE (один эндпоинт вместо двух)
• Готов к OAuth — интегрируется с OAuth 2.1 потоком Kodik

Поля конфигурации

{
  "servers": {
    "my-http-server": {
      "type": "http", // "streamableHttp" тоже принимается
      "url": "https://example.com/mcp",
      "headers": { "X-Custom": "value" },
    },
  },
}

Когда использовать streamable HTTP

• Любой новый сервер, который вы создаёте или к которому подключаетесь
• Сервисы, документирующие единый эндпоинт /mcp (вместо отдельных /sse и /message)
• Серверы, требующие OAuth 2.1

Выбор транспорта

Сервер работает на вашей локальной машине?
  Да → stdio

Сервер использует два эндпоинта (/sse и /message)?
  Да → sse

В остальных случаях → http (streamable HTTP)

Подробные параметры конфигурации, применимые ко всем типам транспортов (режимы одобрения, фильтрация инструментов, OAuth), см. в Настройка MCP Серверов.