Мой дэйли дайджест

одно техническое понятие в день

Мастер Claude · Блок 6. MCP и интеграции

Урок 52 из 93 · ~10 мин чтения

4 транспорта MCP: http/stdio/sse/ws

Урок пока закрыт

Курс проходится последовательно.

К текущему уроку

Почему это важно именно вам

Вы уже знаете, что MCP — это способ дать Claude инструменты: доступ к базе данных, к Google Sheets, к корпоративному API. Вчера (День 51) мы разобрали саму концепцию MCP. Теперь встаёт практический вопрос: как именно подключить сервер? Не в теории, а конкретно — какую команду набрать, чтобы Claude начал пользоваться вашим инструментом.

Проблема в том, что MCP-серверы бывают разными по своей природе. Один живёт на удалённом хосте где-то в облаке — как веб-сервис. Другой запускается прямо на вашем компьютере как обычная программа. Третий держит постоянное соединение для получения уведомлений в реальном времени. Это не один и тот же механизм, и способ подключения к ним отличается.

Когда директор по развитию настраивает аналитический стек, он не задаётся вопросом «а по какому протоколу работает моя CRM». Но если он хочет подключить эту CRM к Claude через MCP — ему придётся сделать один конкретный выбор: http, stdio или ws. Неправильный выбор означает, что подключение либо не заработает вовсе, либо будет работать ненадёжно. Правильный выбор занимает одну строку в терминале.

Что это такое

Представьте, что вы наняли курьера доставить документ из точки А в точку Б. Документ один, задача одна, но способов выполнить её несколько: пешком, на велосипеде, через специальную курьерскую службу с трекингом, или через автомат с кодом. Результат один и тот же — документ доставлен — но механизм, скорость и надёжность разные в зависимости от ситуации.

Транспорт в MCP — это именно такой способ доставки. Claude отправляет запрос («позвони в инструмент, получи данные»), а транспорт определяет, как физически идёт этот запрос туда и ответ обратно.

Четыре варианта транспорта:

HTTP (Streamable HTTP) — это веб-запрос. Claude обращается к серверу по обычному адресу вида https://mcp.example.com, как браузер обращается к сайту. Сервер живёт где-то в интернете или в корпоративной сети, работает 24/7, вам не нужно его запускать вручную. Это рекомендуемый способ для облачных инструментов.

stdio — это локальный процесс. Claude запускает программу прямо на вашем компьютере (через npx, node, python и т.д.) и общается с ней через стандартные потоки ввода-вывода. Грубая аналогия: вы открываете терминал, запускаете скрипт, он отвечает вам в том же окне. Это рабочий вариант для локальных инструментов — например, для работы с файловой системой или локальной базой данных.

SSE (Server-Sent Events) — устаревший транспорт, который был в ранних версиях MCP. Технически он работает, но официально не рекомендуется: его заменил HTTP-транспорт, который более гибкий. Если видите SSE в старых инструкциях — это признак устаревшей документации.

WebSocket (ws) — постоянное двустороннее соединение. В отличие от HTTP (запрос-ответ), WebSocket держит открытый канал и позволяет серверу самому отправлять данные клиенту без запроса. Это нужно для сценариев реального времени: мониторинг событий, live-уведомления, потоковые данные.

Ключевое различие между http и stdio

HTTP-сервер существует независимо от вас — вы его не запускаете, он просто доступен по адресу. stdio-сервер запускается каждый раз, когда Claude его вызывает, работает пока нужен, и завершается. Первое — как веб-сайт. Второе — как скрипт в терминале.

Как работает на практике

Все четыре транспорта подключаются одной командой: claude mcp add. Разница — в параметрах.

HTTP-транспорт

Базовый синтаксис:

claude mcp add --transport http имя-сервера https://адрес-сервера/путь

Конкретный пример — подключение MCP-сервера аналитики:

claude mcp add --transport http analytics https://mcp.mycompany.com/analytics

Что здесь происходит:
- --transport http — указываем тип транспорта явно
- analytics — имя, под которым этот инструмент будет доступен Claude
- последний аргумент — URL сервера

Если сервер требует авторизацию (а обычно требует), добавляем заголовок:

claude mcp add --transport http analytics https://mcp.mycompany.com/analytics \
  --header "Authorization: Bearer ваш-токен"

Проверить, что подключилось:

claude mcp list

Посмотреть детали конкретного сервера:

claude mcp get analytics

Про область видимости

По умолчанию MCP-сервер добавляется в локальный конфиг текущего проекта. Если хотите, чтобы он был доступен во всех проектах — добавьте флаг --scope user. Подробнее о scopes — День 53.

stdio-транспорт

Синтаксис немного другой, потому что нужно указать не URL, а команду для запуска:

claude mcp add имя-сервера -- команда [аргументы...]

Заметьте: для stdio флаг --transport stdio не нужен — это транспорт по умолчанию.

Пример — подключение сервера для работы с файловой системой:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/вы/Documents

Что здесь происходит:
- filesystem — имя сервера
- npx -y @modelcontextprotocol/server-filesystem — команда запуска (npx скачает и запустит пакет)
- /Users/вы/Documents — аргумент для сервера (папка, к которой даём доступ)

Ещё пример — подключение сервера для работы с базой данных SQLite:

claude mcp add mydb -- npx -y @modelcontextprotocol/server-sqlite /path/to/database.db

Для Python-скрипта:

claude mcp add custom-tool -- python3 /Users/вы/scripts/my_mcp_server.py

npm/npx должны быть установлены

stdio-серверы часто запускаются через npx. Если Node.js не установлен — команда упадёт с ошибкой. Проверьте: node --version. Если нет — установите Node.js с nodejs.org.

WebSocket-транспорт

claude mcp add-json live-monitor '{"type":"ws","url":"ws://localhost:8765"}'

или для защищённого соединения:

claude mcp add-json live-monitor '{"type":"ws","url":"wss://realtime.mycompany.com/mcp"}'

WebSocket использует схему ws:// или wss:// (защищённый), не http://. Это принципиально — перепутать легко.

SSE-транспорт (для справки)

claude mcp add --transport sse legacy-server https://old-server.example.com/sse

Эта команда работает, но если вы встретили MCP-сервер, который требует SSE — стоит уточнить у провайдера, нет ли более новой HTTP-версии.

Управление серверами

Посмотреть все подключённые серверы:

claude mcp list

Удалить сервер:

claude mcp remove имя-сервера

Сбросить доверие (если сервер запрашивал разрешения):

claude mcp reset-project-choices

Частые ошибки

Ошибка 1: Перепутали http и ws в URL.

Симптом: сервер подключился, но при вызове инструмента выдаёт ошибку подключения.

# Неправильно: WebSocket-сервер, а транспорт http
claude mcp add --transport http bad-example ws://localhost:8765

# Правильно
claude mcp add-json good-example '{"type":"ws","url":"ws://localhost:8765"}'

Правило простое: если адрес начинается на ws:// или wss:// — транспорт должен быть ws. Если на http:// или https:// — транспорт http.

Ошибка 2: Пропустили флаг --transport для http-серверов.

# Неправильно: без --transport Claude попробует запустить URL как программу
claude mcp add analytics https://mcp.mycompany.com/analytics

# Правильно
claude mcp add --transport http analytics https://mcp.mycompany.com/analytics

Без флага --transport Claude считает, что вы используете stdio и пытается запустить строку как команду. URL как команда не запустится, получите ошибку.

Ошибка 3: stdio-сервер не находит нужную программу.

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /docs
# Error: spawn npx ENOENT

Это значит, что npx не найден в PATH. В Claude Code это происходит потому, что он может использовать ограниченное окружение. Решение — указать полный путь:

which npx  # найдите полный путь, например /usr/local/bin/npx
claude mcp add filesystem -- /usr/local/bin/npx -y @modelcontextprotocol/server-filesystem /docs

Ошибка 4: Добавили сервер в скоуп local, а нужен был user.

Вы добавили удобный инструмент через claude mcp add, работаете в другом проекте — инструмента нет. Потому что по умолчанию сервер добавляется только для текущего проекта.

# Добавить для всех проектов текущего пользователя
claude mcp add --scope user --transport http analytics https://mcp.mycompany.com/analytics

После этого сервер будет доступен в любом проекте.

SSE в продакшне — не используйте

Если поставщик MCP-инструмента предлагает только SSE-подключение — это тревожный сигнал. Стандарт SSE в MCP объявлен устаревшим. Либо ищите HTTP-версию, либо уточните у разработчика сервера.

Когда нужно / когда нет

Используйте HTTP когда:
- Сервер размещён в облаке или корпоративной сети
- Инструмент должен быть доступен всегда, без запуска вручную
- Вы подключаете сторонний сервис: Notion, Slack, CRM, аналитику
- Нескольким людям нужен доступ к одному MCP-серверу

Примеры из директорской практики: подключить корпоративный сервер аналитики, который IT-отдел поднял в инфраструктуре. Подключить готовый MCP-сервис для работы с Notion. Подключить API подрядчика, который сделал MCP-обёртку.

Используйте stdio когда:
- Инструмент работает на вашем компьютере
- Нужен доступ к локальным файлам, локальной базе данных
- Вы разворачиваете готовый npm-пакет с MCP-сервером
- Инструмент не нужен другим — только вам

Примеры: подключить локальный сервер для работы с Excel-файлами в определённой папке. Запустить сервер для работы с SQLite-базой данных на вашем компьютере. Поднять скрипт, который читает ваши локальные конфиги.

Используйте WebSocket когда:
- Нужны события в реальном времени (не запрос-ответ, а подписка)
- Сервер должен сам уведомлять Claude о происходящем
- Работаете с потоковыми данными: биржевые котировки, мониторинг систем, live-логи

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

Не используйте SSE — нет сценария, где SSE лучше HTTP. Если видите его в документации — ищите актуальную версию.

Практическое правило выбора

Задайте себе один вопрос: «Я запускаю что-то на своём компьютере или обращаюсь к чему-то в сети?» Если на компьютере — stdio. Если в сети — http. WebSocket — только если нужен live-stream.

Связь с другими уроками

День 51 (вчера) — Введение в MCP. Там мы разобрали, что такое MCP и зачем оно нужно. Сегодняшний урок — прямое продолжение: теперь вы знаете механизм, пора разобраться с подключением.

День 53 (завтра) — Scopes в MCP: local/user/project. Сегодня мы вскользь упомянули флаг --scope user. Завтра разберём подробно: в чём разница между локальным, пользовательским и проектным scope, и как правильно организовать конфигурацию, чтобы не пришлось каждый раз заново подключать одни и те же серверы.

День 41 (Фаза 5) — Хуки и PreToolUse. Если вы хотите контролировать, что Claude делает при вызове MCP-инструментов — хуки позволяют перехватывать эти вызовы. PreToolUse сработает перед тем, как Claude обратится к вашему MCP-серверу. Это важно при работе с инструментами, которые могут изменять данные.

Задание на сегодня

Подключите один MCP-сервер через stdio и убедитесь, что он работает.

Конкретно: подключите официальный сервер для работы с файловой системой. Он бесплатный, входит в официальные пакеты MCP, и показывает принцип stdio-транспорта на практике.

# Шаг 1: убедитесь, что node установлен
node --version

# Шаг 2: подключите сервер (укажите папку, с которой хотите работать)
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/ваш-логин/Documents

# Шаг 3: проверьте, что появился в списке
claude mcp list

# Шаг 4: откройте Claude и спросите:
# "Покажи список файлов в Documents"

Критерий «выполнено»: в выводе claude mcp list появился сервер filesystem, и Claude ответил на вопрос о файлах, не сказав «у меня нет доступа к файловой системе».

Если npx не нашёлся — это нормально, выполните which npx и укажите полный путь.

Резюме

Следующий урок откроется после отметки.