MCP stdio не подключается из-за логов в stdout
В stdio-режиме оставьте stdout для сообщений протокола, а диагностические логи направьте в stderr. Обычная приветственная строка может сломать обмен ещё до первого вызова инструмента.
Пример из разработки
При ручном запуске сервер пишет «Service started» и выглядит исправным. MCP-клиент сообщает об ошибке разбора ответа. Разработчик ищет проблему в JSON Schema, хотя первым байтом потока стала буква из служебного сообщения. Та же ошибка появляется, если библиотека печатает баннер, команда установки пишет прогресс или отладочный print остался внутри обработчика.
Почему это работает
Запустите ту же команду и разделите потоки вывода. В stdout должны попадать только допустимые сообщения MCP, а не отладочные строки между ними. В спецификации транспорта версии 2025-06-18 это отдельное требование. Убедитесь, что исключения и сторонние библиотеки тоже не печатают произвольный текст в протокольный канал. Не удаляйте диагностику полностью: без stderr трудно понять, почему дочерний процесс завершился. Сообщения журнала следует ограничивать и очищать от секретных значений.
Проверка перед использованием
| Проверка | Ожидаемое поведение |
|---|---|
| Запуск сервера той же командой, что использует клиент | Первое сообщение stdout корректно разбирается как сообщение протокола; баннера и прогресса установки нет. |
| Ошибка обработчика инструмента | Клиент получает согласованный ответ, а техническая причина доступна в диагностическом потоке без смешивания каналов. |
| Включение подробного логирования | Объём stderr меняется, но формат и последовательность сообщений stdout остаются корректными. |
Проверьте оболочку команды запуска: она тоже может печатать сообщения в stdout до старта сервера. Правильный обработчик MCP не исправит поток, который уже испорчен внешним скриптом или установщиком.
Перенос логов не исправит неверную команду запуска, отсутствие пакета или несовместимую версию протокола. Проверяйте эти причины отдельно после подтверждения чистоты протокольного потока.
Диагностика транспорта — полезный навык для разработки MCP-серверов, которые должны работать внутри реального клиентского приложения. В платном курсе AI Agent Integrations PRO: MCP можно продолжить изучение соответствующего инженерного направления. Перед покупкой сравните программу и открытые материалы со своей задачей.
Описанный протокольный контракт относится к версии 2025-06-18; для другой согласованной версии клиента и сервера сверьте соответствующую спецификацию.
Документация для проверки технических деталей: Транспорты MCP: спецификация 2025-06-18.
Следующий шаг: MCP-интеграции: контракты инструментов, ошибки и доступ. По смежным вопросам: readOnlyHint в MCP: почему аннотация не даёт защиту, Поле отсутствует или равно null в MCP: почему это разные запросы.
