Подключаем MCP-серверы к Claude Code: пошаговый гайд

Claude Code умеет работать не только с файлами вашего проекта, но и с внешними системами — трекерами задач, базами данных, мониторингом, дизайн-инструментами. Мостом между моделью и этими системами служит MCP (Model Context Protocol) — открытый стандарт, через который Claude получает доступ к чужим инструментам и данным. Подключив нужный MCP-сервер один раз, вы перестаёте копировать данные в чат вручную: Claude сам читает задачу в трекере, смотрит ошибку в мониторинге или выполняет запрос к базе. В этом гайде разберём все способы подключения серверов к Claude Code, области видимости, аутентификацию и типичные проблемы.

Что такое MCP и когда он нужен

MCP — это протокол, по которому Claude обращается к внешним «серверам». Каждый сервер отдаёт набор инструментов (tools), а также может отдавать ресурсы и готовые промпты. Если хотите разобраться в самой идее с нуля, начните с заметки что такое MCP простыми словами, а обзор популярных серверов и критерии выбора есть в материале MCP-серверы: обзор и как выбрать под задачу. Хороший сигнал, что пора подключить сервер, — момент, когда вы в очередной раз вставляете в чат текст из другого приложения. Базовые команды работы с проектом описаны в практическом гайде по Claude Code.

Три транспорта: HTTP, stdio и SSE

Сервер подключают командой claude mcp add. Отличаются серверы транспортом — способом, которым Claude Code общается с ними. Транспортов три, и выбор зависит от того, где живёт сервер: в облаке или на вашей машине.

Удалённый HTTP-сервер (рекомендуется)

HTTP — основной транспорт для облачных сервисов. Синтаксис простой: имя и URL.

# Базовый синтаксис
claude mcp add --transport http <имя> <url>

# Реальный пример: подключаем Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# С токеном в заголовке
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer ВАШ_ТОКЕН"

В JSON-конфигурации (файл .mcp.json или команда claude mcp add-json) тип HTTP можно записать как http или как streamable-http — это синонимы, поэтому конфигурации из документации сервера работают без правок. Важная тонкость: если в JSON-записи есть url, но нет поля type, Claude Code примет её за локальный stdio-сервер и пропустит с ошибкой. Всегда указывайте "type": "http" для удалённых серверов.

Локальный stdio-сервер

Stdio-серверы запускаются как процессы на вашей машине — подходят для инструментов, которым нужен прямой доступ к системе или к локальным скриптам. Ключевая деталь синтаксиса — двойное тире --, которое отделяет опции самого Claude Code от команды запуска сервера.

# Базовый синтаксис
claude mcp add [опции] <имя> -- <команда> [аргументы...]

# Пример: сервер Airtable через npx
claude mcp add --env AIRTABLE_API_KEY=ВАШ_КЛЮЧ --transport stdio airtable \
  -- npx -y airtable-mcp-server

Всё, что стоит после --, передаётся серверу как есть. Без этого разделителя Claude Code попытается разобрать флаги сервера (например, --port) как свои и упадёт. Переменные окружения задаются флагом --env (короткий вариант -e), причём между --env и именем сервера должна стоять хотя бы одна другая опция, иначе CLI примет имя за очередную пару KEY=value. Хотите написать свой сервер? Смотрите гайд как создать свой MCP-сервер.

SSE — устаревший транспорт

Transport SSE (Server-Sent Events) объявлен устаревшим (deprecated); используйте HTTP везде, где это возможно. Но некоторые сервисы всё ещё отдают только SSE-эндпоинт — тогда команда та же, но с --transport sse:

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

Области видимости: local, project, user

При добавлении сервера важно выбрать область видимости (scope) — она определяет, в каких проектах сервер загрузится и попадёт ли он в общий доступ команды. Областей три, задаются флагом --scope (или -s).

local — область по умолчанию. Сервер доступен только вам и только в текущем проекте; конфигурация хранится в вашем домашнем файле ~/.claude.json. Подходит для личных и экспериментальных серверов, а также для серверов с секретами, которые не стоит класть в репозиторий.

project — сервер записывается в файл .mcp.json в корне проекта. Этот файл коммитят в систему контроля версий, чтобы вся команда получила одинаковый набор инструментов. Из соображений безопасности Claude Code спрашивает подтверждение, прежде чем использовать серверы из .mcp.json.

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

# Явно указать область
claude mcp add --transport http stripe --scope local https://mcp.stripe.com
claude mcp add --transport http shared --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Если один и тот же сервер объявлен в нескольких местах, Claude Code берёт определение из источника с наивысшим приоритетом: local → project → user → серверы из плагинов → коннекторы claude.ai. Поля из разных областей не смешиваются — используется вся запись целиком.

Аутентификация: OAuth и токены

Многие облачные серверы требуют входа. Claude Code поддерживает OAuth 2.0: добавляете сервер обычной командой, затем внутри сессии набираете /mcp и проходите вход в браузере. После этого сервер показывает статус connected в меню /mcp.

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
# затем внутри Claude Code:
/mcp

Начиная с версии 2.1.186 вход можно запустить прямо из терминала, не открывая панель /mcp:

claude mcp login sentry
# сбросить сохранённые данные:
claude mcp logout sentry

Токены хранятся в системном хранилище (keychain на macOS) и обновляются автоматически. Если сервер использует не OAuth, а собственную схему (Kerberos, короткоживущие токены, внутренний SSO), заголовки можно генерировать на лету через параметр headersHelper в JSON-конфигурации — команда выполняется при каждом подключении, а её вывод в формате JSON подставляется в заголовки запроса.

Управление серверами и проверка статуса

После настройки серверами удобно управлять из командной строки:

claude mcp list          # список всех серверов и их статус
claude mcp get notion    # детали конкретного сервера
claude mcp remove notion # удалить сервер
/mcp                     # внутри Claude Code — статус и вход

Команда claude mcp add подтверждает успех строкой Added ... — это значит, что конфигурация записана, но не проверена на валидность учётных данных. Реальный статус подключения покажет claude mcp list: рядом с каждым сервером появится ✔ Connected, ! Needs authentication или ✘ Failed to connect. Статус ошибки означает именно проблему с сервером, а не сбой самой команды. Временно отключить сервер, не удаляя конфигурацию, можно переключателем в панели /mcp.

Ресурсы и промпты MCP

Помимо инструментов сервер может отдавать ресурсы и промпты. Ресурсы подключаются через упоминание с @, как файлы: наберите @, и в автодополнении появятся ресурсы всех подключённых серверов. Формат ссылки — @сервер:протокол://путь:

Проанализируй @github:issue://123 и предложи исправление

Промпты сервера становятся slash-командами вида /mcp__имясервера__имяпромпта. Наберите /, чтобы увидеть их в списке, и передавайте аргументы через пробел:

/mcp__github__pr_review 456

Масштабирование: поиск инструментов

Когда серверов много, их инструменты могут занять весь контекст. Чтобы этого не происходило, в Claude Code по умолчанию включён поиск инструментов (tool search): при старте сессии загружаются только имена инструментов, а полные описания подтягиваются по мере надобности. Благодаря этому подключение новых серверов почти не влияет на контекстное окно. Если какой-то сервер должен быть виден всегда, добавьте ему в конфигурацию поле "alwaysLoad": true.

Типичные проблемы

Сервер не подключается — сначала посмотрите статус в claude mcp list или /mcp. Частые причины: неверный или просроченный токен (✘ Failed to connect при заданном заголовке Authorization), забытое поле type в JSON, отсутствие -- перед командой stdio-сервера. При обрыве связи HTTP- и SSE-серверы переподключаются автоматически с экспоненциальной задержкой (до пяти попыток); stdio-серверы как локальные процессы автоматически не перезапускаются. Тайм-аут запуска регулируется переменной MCP_TIMEOUT, а лимит объёма ответа инструмента — переменной MAX_MCP_OUTPUT_TOKENS (по умолчанию 25 000 токенов).

Не забывайте о безопасности

MCP-сервер — это сторонний код, который получает доступ к вашим данным и инструментам. Подключайте только те серверы, которым доверяете: сервер, который тянет внешний контент, способен открыть путь для промпт-инъекции. Для баз данных используйте read-only учётную запись в строке подключения, храните секреты в переменных окружения, а не в командах, и держите общие серверы в .mcp.json под ревью команды.

Вывод

Подключение MCP-сервера к Claude Code сводится к одной команде claude mcp add с правильным транспортом: HTTP для облачных сервисов, stdio для локальных инструментов, SSE — только если у сервиса нет альтернативы. Дальше выбираете область видимости под задачу, при необходимости проходите OAuth через /mcp и проверяете статус в claude mcp list. Начните с одного сервера, который закроет вашу самую частую рутину, — и постепенно соберёте набор инструментов, превращающий Claude Code из редактора кода в полноценного помощника, работающего с вашими системами напрямую.