Четыре способа подключить MCP-сервер в Claude Code: HTTP, SSE, stdio и WebSocket

Claude Code умеет работать не только с файлами проекта и терминалом. Через MCP его можно подключить к внешним инструментам и данным: корпоративному API, базе данных, issue tracker, системе мониторинга или собственному внутреннему сервису.

Это особенно заметно на простом примере. Без MCP разработчик находит задачу в трекере, копирует её описание в Claude, затем отдельно приносит данные из другой системы. С MCP Claude Code может обращаться к подключённому инструменту самостоятельно — в пределах тех возможностей, которые предоставляет конкретный MCP-сервер.

MCP, или Model Context Protocol, — открытый стандарт интеграции AI-приложений с инструментами и источниками данных. Сам MCP-сервер не обязательно является только «посредником»: он может предоставлять Claude инструменты, данные или собственную логику, а уже внутри обращаться к API, базе или другой системе. Anthropic описывает MCP как способ дать Claude Code доступ к tools, databases и APIs.

Первый практический вопрос после выбора MCP-сервера — как именно подключить его к Claude Code. В актуальной документации Anthropic описаны четыре транспорта:

Эти варианты не равнозначны. Для новых удалённых MCP-серверов Anthropic рекомендует HTTP; SSE уже помечен как deprecated. stdio решает другую задачу — запускает MCP-сервер локально. WebSocket нужен, когда серверу требуется постоянный двусторонний канал.

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

Упрощённо схема выглядит так:

Claude Code
     ↓
 MCP-сервер
     ↓
API / база / сервис / локальный инструмент

Claude Code видит только те возможности, которые сервер ему предоставляет. Один сервер может позволять только читать данные, другой — создавать задачи, изменять записи или запускать действия.

Поэтому транспорт отвечает прежде всего на вопрос «как Claude Code связывается с MCP-сервером?», а не «что Claude разрешено делать».

Это важное различие. HTTP сам по себе не делает интеграцию безопасной или небезопасной, а локальный stdio не означает автоматически ограниченный доступ.

1. HTTP — основной вариант для удалённых MCP-серверов

Для нового удалённого подключения в большинстве случаев стоит сначала проверить HTTP.

Anthropic прямо называет HTTP рекомендуемым вариантом для remote MCP servers и наиболее широко поддерживаемым транспортом среди облачных сервисов.

Базовая команда выглядит так:

claude mcp add --transport http <name> <url>

Например:

claude mcp add --transport http notion https://mcp.notion.com/mcp

Здесь notion — имя, под которым сервер будет отображаться в Claude Code, а URL — адрес MCP endpoint.

Если сервер использует токен в HTTP-заголовке, его можно передать через --header:

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Обе формы приведены в текущей документации Claude Code.

Когда выбирать HTTP

HTTP подходит для большинства сценариев, где MCP-сервер находится в сети и работает по обычной логике «клиент отправил запрос — сервер ответил».

Это может быть SaaS, внутренний сервис компании или собственный MCP endpoint.

Для HTTP Claude Code также поддерживает OAuth. Сервер можно добавить командой claude mcp add, а затем пройти авторизацию через /mcp или командой claude mcp login <name>. Токены после успешного входа сохраняются и обновляются Claude Code.

Для обычного удалённого сервера правило простое:

Если нет специальной причины выбрать другой транспорт, начинайте с HTTP.

2. SSE — поддерживается, но уже устаревает

SSE расшифровывается как Server-Sent Events. Ранее этот вариант широко использовался удалёнными MCP-серверами.

Сейчас Anthropic прямо помечает SSE transport как deprecated и рекомендует использовать HTTP там, где он доступен.

Прямое SSE-подключение всё ещё поддерживается:

claude mcp add --transport sse <name> <url>

Например:

claude mcp add --transport sse asana https://mcp.asana.com/sse

Но в современных версиях Claude Code есть более удобный вариант. Если сервис предоставляет только SSE, можно попробовать добавить его обычной HTTP-командой:

claude mcp add --transport http my-server https://example.com/mcp

Начиная с Claude Code 2.1.265 клиент сначала пробует HTTP и, если сервер его не принимает, может автоматически переключиться на SSE. На более старых версиях или при необходимости прямого SSE нужно явно указать --transport sse.

Когда SSE всё ещё нужен

Главный сценарий — совместимость с существующей инфраструктурой.

Если у компании уже работает MCP-сервис, предоставляющий только SSE endpoint, его можно продолжать использовать. Но проектировать новый удалённый MCP вокруг SSE без необходимости уже не стоит.

3. stdio — когда MCP-сервер работает локально

stdio принципиально отличается от HTTP и SSE.

Вместо обращения к удалённому URL Claude Code запускает MCP-сервер как локальный процесс на компьютере пользователя. Anthropic рекомендует этот вариант для инструментов, которым нужен прямой системный доступ, и для собственных локальных скриптов.

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

claude mcp add --transport stdio <name> -- <command>

Например:

claude mcp add --transport stdio myserver -- npx server

Claude Code запустит npx server и будет взаимодействовать с этим процессом через stdin и stdout.

Зачем нужен двойной дефис --

В stdio-команде есть важная деталь:

--

Он отделяет параметры Claude Code от параметров программы, запускающей MCP-сервер.

Например:

claude mcp add --env KEY=value --transport stdio myserver \
  -- python server.py --port 8080

До -- находятся параметры Claude Code:

--env KEY=value
--transport stdio

После -- — команда локального MCP-сервера:

python server.py --port 8080

Если разделитель убрать, Claude Code может попытаться интерпретировать, например, --port как собственный параметр. Anthropic отдельно обращает внимание на этот нюанс в документации.

Когда выбирать stdio

stdio хорошо подходит для внутренних утилит, Python- или Node.js-скриптов, CLI-инструментов и других серверов, которые должны работать непосредственно в локальной среде разработчика.

Claude Code также передаёт локальному процессу переменную CLAUDE_PROJECT_DIR с корнем проекта. Это позволяет серверу находить файлы относительно проекта, не полагаясь на текущую рабочую директорию.

Здесь особенно важно контролировать права самого локального процесса. Если stdio-сервер запускается от имени пользователя, он потенциально получает те же возможности, которые доступны этому процессу: файлы, переменные окружения, сетевые ресурсы и учётные данные.

Локальный транспорт — не синоним ограниченного доступа.

4. WebSocket — для постоянного двустороннего соединения

WebSocket — более специализированный вариант.

Такой сервер поддерживает постоянное двустороннее соединение с Claude Code. Anthropic рекомендует WebSocket для удалённых MCP-серверов, которым нужно самостоятельно отправлять события Claude без предварительного запроса с его стороны.

Например, это может пригодиться, если активная сессия должна получать:

новое событие
      ↓
 MCP-сервер
      ↓
 Claude Code

без постоянного опроса сервера.

Если MCP только отвечает на обычные запросы Claude, Anthropic рекомендует использовать HTTP.

Как добавить WebSocket MCP

В отличие от первых трёх вариантов, команда вида:

claude mcp add --transport ws

не поддерживается.

WebSocket-сервер нужно настроить в .mcp.json либо добавить через claude mcp add-json:

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

WebSocket поддерживает авторизацию через headers, но не использует OAuth-механизм HTTP-серверов.

Поэтому WebSocket имеет смысл выбирать не потому, что он «современнее» HTTP, а только если архитектура действительно требует постоянного соединения или push-событий.

Как выбрать транспорт за минуту

Для большинства проектов достаточно такой логики:

Где работает MCP?
                      │
          ┌───────────┴───────────┐
       локально                 удалённо
          │                        │
        stdio               Нужны push-события?
                                   │
                            ┌──────┴──────┐
                           нет            да
                            │              │
                          HTTP        WebSocket

         SSE → в основном для совместимости
               со старыми серверами

То есть выбор чаще всего выглядит так:

локальный процесс → stdio;

обычный удалённый сервис → HTTP;

удалённый сервис с push-событиями → WebSocket;

старый MCP endpoint → возможно SSE.

Local, Project и User: кому будет доступен сервер

После выбора транспорта нужно определить scope — область действия подключения.

Claude Code поддерживает три уровня.

Local

Local используется по умолчанию.

claude mcp add --transport http stripe https://mcp.stripe.com

Такой сервер доступен пользователю только в текущем проекте и не попадает в репозиторий.

Это удобно для тестов, персональных MCP и локальных настроек.

Project

Если одно подключение должно использоваться всей командой:

claude mcp add --transport http shared-server \
  --scope project https://example.com/mcp

Claude Code создаст или обновит .mcp.json в корне проекта. Этот файл можно хранить в Git, чтобы участники команды получали одинаковую конфигурацию MCP.

Есть важная защита: в обычной интерактивной сессии Claude Code просит пользователя подтвердить новый project-scoped сервер из .mcp.json перед использованием. Поэтому простое клонирование чужого репозитория не должно автоматически активировать записанный в нём MCP-сервер без участия пользователя.

User

Если сервер должен быть доступен одному пользователю во всех его проектах:

claude mcp add --transport http hubspot \
  --scope user https://mcp.hubspot.com/anthropic

Такое подключение остаётся персональным, но работает в разных проектах этой машины.

Если сервер с одним именем определён сразу в нескольких scope, текущая документация задаёт приоритет local → project → user. Конфигурации между уровнями не объединяются: используется целиком запись с более высоким приоритетом.

Как не положить секрет в Git

Project scope удобен, но .mcp.json может находиться в системе контроля версий. Поэтому API-ключи и токены не стоит вписывать туда напрямую.

Claude Code поддерживает подстановку переменных окружения.

Например:

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

В репозитории остаётся ${API_KEY}, а реальное значение задаётся отдельно в окружении пользователя. Подстановку можно использовать в command, args, env, URL и headers.

Это позволяет делиться общей конфигурацией сервера, не коммитя сам секрет.

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

Команда claude mcp add подтверждает, что конфигурация записана. Она ещё не означает, что соединение с сервером успешно установлено.

Для проверки можно использовать:

claude mcp list

Для подробностей по одному серверу:

claude mcp get <name>

А непосредственно внутри Claude Code:

/mcp

Claude Code отображает состояния вроде Connected, Needs authentication и Failed to connect. (Claude)

Например:

claude mcp get notion

позволяет проверить конкретное подключение.

У WebSocket есть отдельный нюанс: такие серверы сейчас не отображаются в claude mcp list. Для них Anthropic рекомендует использовать claude mcp get <name> или панель /mcp.

Что делать, если сервер требует OAuth

Для HTTP MCP-серверов Claude Code поддерживает OAuth.

Сначала сервер добавляют как обычно:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Затем можно открыть:

/mcp

и пройти авторизацию в браузере. Альтернативный вариант:

claude mcp login sentry

Команда claude mcp login поддерживается в актуальных версиях Claude Code и позволяет запустить OAuth flow прямо из терминала.

Если вы вручную задали Authorization в headers, а сервер отверг этот credential, Claude Code не переключается автоматически на OAuth. В таком случае нужно исправить токен или убрать заголовок и использовать OAuth flow.

Транспорт не определяет безопасность

Одна из самых опасных ошибок при выборе MCP — считать:

stdio локальный, значит безопасный;

или:

HTTP удалённый, значит менее безопасный.

Этого нельзя утверждать без информации о конкретной конфигурации.

Для удалённого MCP важны сам сервер, его владелец, механизм авторизации, передаваемые данные и права используемых credentials.

Для локального stdio важны права процесса: какие файлы он может читать, какие переменные окружения получает и к каким внутренним ресурсам имеет доступ.

Anthropic отдельно предупреждает, что MCP-серверы, которые получают внешний контент, могут создавать риск prompt injection, поэтому перед подключением необходимо убедиться, что серверу можно доверять.

Главный принцип:

MCP-транспорт определяет канал связи. Права и границы доступа нужно проектировать отдельно.

Для разработчиков MCP-серверов: как всегда требовать подтверждение

Этот механизм не нужен при обычном подключении готового MCP, но полезен разработчикам собственных серверов.

Если конкретный MCP tool никогда не должен выполняться без явного согласия человека, его можно пометить:

{
  "_meta": {
    "anthropic/requiresUserInteraction": true
  }
}

Тогда Claude Code будет показывать permission prompt при каждом вызове этого инструмента и не предложит вариант «больше не спрашивать».

Аннотация поддерживается начиная с Claude Code 2.1.199. На более старых версиях она игнорируется.

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

Практические сценарии

Облачный сервис

Есть MCP endpoint:

https://example.com/mcp

Для первого подключения логично использовать:

claude mcp add --transport http example https://example.com/mcp

HTTP здесь соответствует рекомендуемому сценарию удалённого сервера.

Собственный локальный скрипт

Компания написала:

python company_mcp.py

Тогда сервер можно подключить через stdio:

claude mcp add --transport stdio company-tools \
  -- python company_mcp.py

Не обязательно разворачивать отдельный HTTP-сервис, если инструмент нужен локально.

Сервер должен сам сообщать о событиях

Если активная сессия Claude должна получать внешние события без постоянного опроса сервера, появляется смысл рассмотреть WebSocket:

claude mcp add-json events \
  '{"type":"ws","url":"wss://mcp.example.com/socket"}'

Если push-события не нужны, HTTP обычно проще.

Пошаговая настройка первого MCP

Для первого подключения не нужно заранее разбираться во всех тонкостях протокола.

Шаг 1. Определите, где находится сервер. Если это локальная программа — смотрите в сторону stdio. Для удалённого сервера начните с HTTP.

Шаг 2. Добавьте сервер.

Например:

claude mcp add --transport http example https://example.com/mcp

Шаг 3. Проверьте состояние.

claude mcp get example

или:

/mcp

Шаг 4. Пройдите авторизацию, если она нужна. Для HTTP-сервера с OAuth это можно сделать через /mcp или claude mcp login.

Шаг 5. Определите scope. Личное подключение можно оставить local. Общее командное подключение имеет смысл вынести в project scope.

Шаг 6. Проверьте права. Серверу должны быть доступны только те данные и операции, которые действительно нужны для сценария.

После этого уже можно проверять работу самого MCP-инструмента в реальной задаче.

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

Первая — выбирать SSE для нового удалённого MCP. Он всё ещё поддерживается, но официально deprecated; при возможности лучше HTTP.

Вторая — пытаться добавить WebSocket через --transport ws. Такой вариант Claude Code не поддерживает: нужен .mcp.json или claude mcp add-json.

Третья — забывать -- при stdio. Тогда параметры локальной программы могут быть разобраны как параметры Claude Code.

Четвёртая — считать сообщение Added подтверждением рабочего соединения. Оно говорит только о сохранении конфигурации; состояние подключения нужно проверять отдельно.

Пятая — записывать токен непосредственно в общий .mcp.json. Для командной конфигурации разумнее использовать переменные окружения и ${VAR}.

Вывод

Claude Code действительно поддерживает четыре варианта MCP-подключения, но выбирать между ними проще, чем может показаться.

HTTP — основной и рекомендуемый Anthropic вариант для современных удалённых MCP-серверов.

SSE остаётся рабочим, но считается устаревшим и нужен прежде всего для совместимости.

stdio подходит для локальных программ, скриптов и инструментов, которые Claude Code запускает на компьютере пользователя.

WebSocket нужен в специальных сценариях с постоянным двунаправленным соединением и push-событиями.

После выбора транспорта остаются ещё три практических вопроса: где хранить конфигурацию — local, project или user, как сервер будет авторизоваться и какие реальные права он получит.

Именно последний пункт наиболее важен. MCP отвечает за интеграцию Claude Code с инструментом, но не заменяет архитектуру доступа и правила безопасности. Хорошая настройка начинается не с выбора самого «надёжного» транспорта, а с понимания того, где работает сервер, какие данные ему действительно нужны и какие действия через него допустимы.