Как подключить MCP-серверы к Claude Code: команды, области и задачи
В Claude Code 2.1.319 от 6 ноября 2026 года появилась поддержка MCP-задач в терминале. Теперь MCP-серверы, поддерживающие выполнение длительных операций как самостоятельных задач, могут передавать их в фон. Claude продолжает работу, а результат получает после завершения операции.
MCP, или Model Context Protocol, представляет собой открытый стандарт интеграции ИИ с внешними инструментами. Через MCP Claude Code взаимодействует с API, базами данных и другими сервисами.
Для подключения предусмотрены удалённые HTTP-серверы, устаревающий SSE, локальный stdio и WebSocket. Способ соединения зависит от возможностей конкретного сервера.
MCP предоставляет Claude инструменты внешних сервисов
MCP-сервер открывает набор действий и данных, доступных модели.
Например, после подключения GitHub Claude Code может работать с issues и pull requests. Через PostgreSQL можно выполнять запросы к данным, а интеграции с Sentry позволяют изучать показатели работы приложения.
Документация Anthropic приводит и более сложные сценарии: получить задачу из Jira, реализовать функцию и создать pull request; использовать макеты Figma из Slack; подготовить черновики писем Gmail.
При поиске серверов Anthropic рекомендует начинать с Anthropic Directory.
Сторонние серверы необходимо проверять перед подключением. Особенно это относится к инструментам, получающим внешнее содержимое, поскольку оно может содержать prompt injection, вредоносные инструкции для модели.
Разбираю Claude Code и ИИ-агентов на практике: как применять их в реальных рабочих задачах, автоматизировать рутину, собирать собственных ИИ-ассистентов и зарабатывать с помощью новых технологий. Практические разборы, инструменты, кейсы и эксперименты: от первого ИИ-агента до полноценных рабочих систем. Подписывайтесь.
HTTP рекомендуется для удалённых MCP-серверов
Основной вариант подключения облачных сервисов использует HTTP.
Синтаксис:
claude mcp add --transport http <name> <url>
Пример подключения Notion:
claude mcp add --transport http notion https://mcp.notion.com/mcp
Если серверу необходим заголовок авторизации, используется --header:
claude mcp add --transport http secure-api https://api.example.com/mcp \
--header "Authorization: Bearer your-token"
В JSON-конфигурации тип streamable-http допускается как обозначение HTTP.
При настройке через JSON требуется явно указывать type. Запись с url, но без type, Claude Code воспринимает как конфигурацию stdio и сообщает об ошибке.
SSE остаётся доступным, но помечен как устаревший
SSE, или Server-Sent Events, представляет собой способ получения событий от сервера.
В документации Anthropic транспорт SSE отмечен как deprecated, то есть устаревший.
Для прямого подключения используется:
claude mcp add --transport sse <name> <url>
Пример с Asana:
claude mcp add --transport sse asana https://mcp.asana.com/sse
Начиная с версии 2.1.265, Claude Code может автоматически переключиться на SSE, если сначала попытаться подключиться через HTTP, а сервер его не принимает.
Поэтому для совместимых серверов документация рекомендует сначала использовать HTTP.
Stdio запускает MCP-сервер локальным процессом
Stdio подходит для программ, которым требуется прямой доступ к локальной системе или выполнение пользовательских скриптов.
Синтаксис:
claude mcp add [options] <name> -- <command> [args...]
Пример Airtable из документации:
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
-- npx -y airtable-mcp-server
Параметры Claude Code необходимо разместить до имени сервера и разделителя --. Сам разделитель отделяет параметры клиента от команды запуска.
Всё после -- передаётся серверному процессу без изменений.
Например:
claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080
Здесь --port 8080 относится к server.py, а не к Claude Code.
При использовании --env необходимо учитывать порядок параметров. Если имя сервера идёт непосредственно после --env, интерфейс командной строки может принять его за очередную переменную и отклонить команду.
Для локальных серверов Claude Code передаёт переменную CLAUDE_PROJECT_DIR, содержащую корневой каталог проекта.
WebSocket поддерживает постоянное двустороннее соединение
В документации также описаны удалённые WebSocket-серверы.
Они подходят для сценариев, когда сервер должен самостоятельно передавать события в Claude без отдельного запроса.
Такие подключения настраиваются через JSON, например:
claude mcp add-json events-server \
'{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'
WebSocket не поддерживается флагом claude mcp add --transport.
Для сервисов, которые только отвечают на запросы, Anthropic рекомендует HTTP. Он также поддерживает OAuth, в отличие от WebSocket.
List, get и remove управляют конфигурацией серверов
После добавления подключения доступны основные команды:
claude mcp list
claude mcp get notion
claude mcp remove notion
Внутри интерактивной сессии используется:
/mcp
claude mcp list показывает статус каждого сервера.
Возможные состояния включают:
• Connected, соединение установлено.
• Needs authentication, требуется авторизация.
• Failed to connect, подключение не удалось.
• Pending approval, проектный сервер ожидает подтверждения.
Также отображается статус временно отключённых серверов.
Отключить сервер без удаления конфигурации можно через панель /mcp. Это действие сохраняется отдельно для проекта.
Удаление удалённого сервера убирает сохранённые Claude Code OAuth-токены и регистрацию клиента, но само по себе не отзывает токены на стороне сервиса.
Для поддерживающих отзыв авторизационных серверов предусмотрена команда claude mcp logout <name> перед удалением.
Local, project и user определяют расположение конфигурации
Claude Code поддерживает три основные области MCP-настроек.
Local
Используется по умолчанию.
Сервер доступен только в текущем проекте. Его конфигурация хранится в ~/.claude.json в записи соответствующего проекта.
Пример:
claude mcp add --transport http stripe --scope local https://mcp.stripe.com
Project
Подключение доступно всем, кто работает с проектом и использует его конфигурацию.
Настройки записываются в .mcp.json в корне проекта.
claude mcp add --transport http shared-server --scope project https://example.com/mcp
Файл можно добавить в Git. При интерактивной работе Claude Code запрашивает подтверждение перед использованием такого сервера.
User
Сервер доступен пользователю во всех его проектах.
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic
Конфигурация сохраняется в ~/.claude.json.
При совпадении имён серверов порядок приоритета следующий: local, project, user, серверы плагинов, коннекторы claude.ai.
Управляемая конфигурация организации может иметь более высокий приоритет.
MCP-задачи в версии 2.1.319 запускаются в фоне сразу
В Claude Code предусмотрены два разных механизма фонового выполнения MCP.
Первый относится к MCP tasks, то есть задачам, которые сервер выполняет самостоятельно.
Например, сервер может принять операцию экспорта отчёта. После принятия работы Claude Code получает сведения о задаче и продолжает диалог.
Когда операция завершится, Claude получит её результат.
В терминале отображается количество активных MCP-задач. Их состояние можно посмотреть через:
/tasks
Для остановки необходимо выбрать задачу и нажать x либо попросить Claude отменить её.
Claude Code прекратит отслеживание и отправит серверу запрос на отмену. Сервер может всё равно завершить уже выполняемую работу.
После завершения в истории появляется сообщение вида:
MCP task <server task id> (<server>/<tool>) completed.
Сам результат передаётся Claude. Пользователь может попросить показать его.
Обычные долгие MCP-вызовы переходят в фон через две минуты
Второй механизм называется Automatic backgrounding of long tool calls.
Если обычный вызов MCP-инструмента из основной сессии продолжается более двух минут, Claude Code переводит его в фон.
Claude получает идентификатор и может выполнять другие действия.
После завершения результат приходит отдельным уведомлением.
Такой вызов остаётся связанным с текущей сессией и не продолжает отслеживаться после выхода.
Порог можно изменить через CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS.
Значение 0 отключает автоматический перевод в фон и заставляет Claude ждать завершения всех MCP-вызовов.
Для отключения фоновых задач и фоновых команд предусмотрено CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1, но эта настройка сама по себе не заставляет Claude ждать MCP tasks.
Автоматический перевод долгого вызова не применяется к вызовам из субагентов и IDE-серверов.
Удалённые MCP-задачи могут пережить закрытие Claude Code
MCP task выполняется самим сервером.
Если сервер удалённый, задача может продолжаться после выхода пользователя из Claude Code.
Для повторного отслеживания нужно возобновить ту сессию, из которой её запустили.
Поддерживаются интерактивные способы:
claude --resume
Также документация описывает claude --continue и /resume.
После восстановления соединения Claude Code снова проверяет состояние задачи, если сервер сохраняет сведения о ней.
Для локального stdio-сервера поведение отличается: его процесс останавливается при выходе из Claude Code. Продолжение работы после завершения процесса зависит от самого сервера.
Не каждый сервер поддерживает MCP tasks. Требуются совместимая версия протокола, подходящая среда и вызов из основного диалога.
Документация указывает поддержку MCP tasks для терминального CLI, Agent SDK и GitHub Actions при соблюдении дополнительных условий. Для VS Code и Desktop такая поддержка не заявлена.
CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND меняет ожидание результата
В версии 2.1.319 появилась переменная:
CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND
Если установить значение 1, Claude будет ожидать завершения MCP task внутри вызова инструмента.
Обычный механизм перевода долгого вызова в фон может продолжать работать. По умолчанию это происходит после двух минут.
В таком случае вызов становится обычной фоновой операцией, а не серверной MCP task, отслеживаемой после выхода из сессии.
Если требуется ожидание каждого MCP-вызова без автоматического перевода в фон, используется:
{
"env": {
"CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS": "0"
}
}
Настройка размещается в settings.json.
GitHub и PostgreSQL можно подключить по готовым примерам
Для подключения GitHub Anthropic приводит удалённый сервер с авторизацией через персональный токен:
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
--header "Authorization: Bearer YOUR_GITHUB_PAT"
После подключения можно запросить ревью pull request.
Для PostgreSQL приводится локальный DBHub:
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
--dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"
Для такого сценария документация рекомендует учётную запись базы данных только с правами чтения.
Проверка обоих подключений выполняется через /mcp.
Источник: документация Claude Code.