Настройка MCP в Claude Code: как добавить серверы

Чтобы настроить MCP в Claude Code, выполните в терминале claude mcp add. Локальный сервер добавляется как claude mcp add <имя> -- <команда>, удалённый — как claude mcp add --transport http <имя> <url>, а --scope определяет, будет ли сервер доступен только вам в этом проекте (local, по умолчанию), всей команде через файл .mcp.json (project) или вам во всех проектах (user). Затем введите /mcp внутри сессии, чтобы проверить подключение и войти на серверы с OAuth.

В этом руководстве разобран каждый шаг: транспорты, разделитель --, переменные окружения и заголовки, scope, ручное редактирование .mcp.json, команды list, get и remove, OAuth, импорт из Claude Desktop, тайм-ауты и лимиты вывода, а также то, что стоит проверить, прежде чем доверять серверам проекта. Команды взяты из документации Claude Code по MCP от Anthropic по состоянию на октябрь 2026 года. Если MCP для вас в новинку, начните со статьи что такое MCP-сервер; какие серверы стоит добавить, описано в подборке лучших MCP-серверов для программирования.

Краткая шпаргалка

Короткие флаги тоже работают: -t вместо --transport, -s вместо --scope, -e вместо --env и -H вместо --header.

Выбор транспорта: stdio, HTTP или SSE

MCP-сервер подключается к Claude Code одним из трёх способов:

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

Добавление локального stdio-сервера

Правило, на котором спотыкаются чаще всего: собственные опции Claude Code (--transport, --scope, --env) пишутся до имени сервера, а всё после -- — это команда сервера, которая передаётся без изменений.

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

# Playwright через npx
claude mcp add playwright -- npx -y @playwright/mcp@latest

# Сервер, которому нужен API-ключ в окружении
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Без -- флаг сервера вроде --port 8080 был бы прочитан как опция Claude Code, и команда завершилась бы ошибкой. Ещё одна ловушка из документации: --env принимает несколько пар KEY=value, поэтому если имя сервера идёт сразу после него, оно читается как очередная пара и отклоняется. Поставьте между ними другую опцию, например --transport stdio, как в примере выше.

Claude Code задаёт CLAUDE_PROJECT_DIR в окружении каждого stdio-сервера, поэтому сервер может найти корень проекта, не завися от рабочего каталога.

Добавление удалённого HTTP-сервера

Удалённому серверу вместо команды передаётся URL. Заголовки добавляются через --header, если сервер требует API-ключ или bearer-токен:

# Облачный сервер со входом через OAuth
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Сервер со статическим токеном
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Заголовок, введённый здесь, сохраняется в файле конфигурации открытым текстом. Для всего, чем вы делитесь, лучше подходят OAuth или ссылка ${VAR} в .mcp.json — о ней ниже.

Если в README сервера уже есть готовое JSON-описание, обойдитесь без флагов и вставьте его через add-json. Команда принимает объект, который лежал бы внутри mcpServers, а не весь файл:

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

Выбор scope

Каждый claude mcp add записывает сервер в один из трёх scope:

claude mcp add --transport http stripe https://mcp.stripe.com                      # local
claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Простое правило: личные инструменты и всё, что содержит ваши учётные данные, — в user или local; серверы, которые нужны всей команде для работы с репозиторием, — в project.

Обратите внимание: «local» здесь — это не .claude/settings.local.json. Локальные MCP-серверы хранятся в ~/.claude.json в домашнем каталоге.

Если одно и то же имя определено в нескольких местах, Claude Code берёт самое приоритетное и не объединяет поля: сначала local, затем project, затем user, затем серверы плагинов, затем коннекторы claude.ai. Если два scope связывают одно имя с разными адресами, claude mcp list и /mcp предупреждают об этом.

Ручное редактирование .mcp.json

Сервер со scope project — это просто файл .mcp.json, который можно править и ревьюить в pull request:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

${VAR} раскрывается в значение переменной окружения, а ${VAR:-default} подставляет значение по умолчанию, если переменной нет. Подстановка работает в command, args, env, url и headers — так файл коммитится без токенов: каждый разработчик задаёт API_KEY в своей оболочке. Если переменной нет и значения по умолчанию тоже нет, claude mcp list и /mcp выдают предупреждение и оставляют текст нераскрытым.

Поле "timeout" у отдельного сервера, в миллисекундах, задаёт жёсткий лимит на вызовы инструментов этого сервера.

Управление серверами: list, get, remove и /mcp

Из оболочки:

claude mcp list          # все серверы и статус подключения
claude mcp get notion    # подробности об одном сервере, в том числе причина сбоя
claude mcp remove notion # удалить из его scope

list и get показывают подробности ошибки со скрытыми учётными данными. Сервер проекта, который вы ещё не одобрили, отображается как ожидающий, пока вы не запустите claude интерактивно и не одобрите его.

Внутри сессии панель управления — это /mcp. Она показывает статус и число инструментов каждого сервера, а в меню сервера можно пройти аутентификацию, пройти её заново, сбросить её, переподключиться или отключить сервер, не удаляя конфигурацию. /mcp reconnect all разом переподключает все упавшие серверы (Claude Code 2.1.284 и новее).

Подключённые серверы дают не только инструменты. Введите @, чтобы сослаться на ресурсы сервера рядом со своими файлами, и /, чтобы увидеть его промпты в виде /servername:promptname (MCP). Сами инструменты называются mcp__<сервер>__<инструмент> — это имя используется в правилах разрешений и в matcher’ах хуков.

Вход на OAuth-серверы

Многие облачные серверы, например Sentry, Notion или Linear, используют OAuth вместо статического токена. Добавьте сервер с --transport http без заголовков, а затем войдите:

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

В Claude Code выполните /mcp, выберите сервер и нажмите Authenticate. Откроется браузер, вы войдёте, а Claude Code сохранит токен и будет его обновлять. То же самое можно сделать из оболочки, не открывая сессию:

claude mcp login sentry               # открывает браузер
claude mcp login sentry --no-browser  # печатает URL, для SSH-сессий
claude mcp logout sentry              # удаляет сохранённые учётные данные

Headless-запуски (claude -p) не могут показать окно входа, поэтому сначала один раз войдите интерактивно. Некоторым серверам нужен фиксированный callback-порт или заранее зарегистрированное OAuth-приложение; для них при добавлении сервера передайте --callback-port, --client-id и --client-secret. Секрет запрашивается со скрытым вводом или читается из MCP_CLIENT_SECRET в CI.

Импорт серверов из Claude Desktop

Если серверы уже настроены в приложении Claude Desktop, вводить их заново не нужно:

claude mcp add-from-claude-desktop

В открывшемся диалоге выбираются серверы для импорта. По состоянию на октябрь 2026 года это работает только на macOS и в WSL. Добавьте --scope user, чтобы импортировать их в пользовательскую конфигурацию. Имена серверов могут содержать только буквы, цифры, дефисы и подчёркивания, поэтому сервер Desktop с пробелом в имени пропускается с сообщением, а уже существующее имя получает суффикс вроде server_1.

Устранение неполадок

У длинных текстовых результатов есть второй лимит: результат длиннее 50 000 символов сохраняется в файл, а не попадает напрямую в контекст.

Удалённые серверы, отвалившиеся посреди сессии, переподключаются до пяти раз с растущей паузой, а stdio-серверы автоматически не перезапускаются, так что упавший локальный сервер нужно переподключить из /mcp.

Второй ресурс, за которым стоит следить, — контекст. На актуальных моделях Claude Code по умолчанию использует поиск инструментов (tool search): при запуске загружаются только имена инструментов и инструкции серверов, а полные определения — когда они понадобятся Claude. Поэтому длинный список серверов обходится дёшево, но каждый сервер — это ещё одна деталь, которая может сломаться или быть использована во вред, так что держите список коротким. В скриптах --mcp-config <файл> подгружает дополнительные серверы на один запуск, а --strict-mcp-config заставляет Claude Code использовать только их.

Безопасность: серверы проекта — это код из репозитория

.mcp.json в репозитории может запустить любую локальную команду или указать на любой URL. Именно это делает его полезным для команд, и именно поэтому Claude Code обращается с ним осторожно:

• Сначала одобрение. В интерактивной сессии Claude Code спрашивает, прежде чем использовать серверы со scope project. claude mcp reset-project-choices сбрасывает ваши прошлые ответы.
• Репозиторий не может одобрить сам себя. Настройки вроде enableAllProjectMcpServers, закоммиченные в .claude/settings.json проекта, игнорируются, пока вы не доверяете папке, и сервер остаётся в ожидании. Одобрения из ваших собственных пользовательских настроек по-прежнему действуют.
• Headless-запуски не спрашивают. В claude -p и в Agent SDK запроса нет, поэтому серверы проекта загружаются без него. Чтобы заблокировать сервер в любом режиме, внесите его в disabledMcpjsonServers.
• Учётные данные остаются дома. В полях url и headers удалённого сервера чувствительные переменные вроде ANTHROPIC_API_KEY раскрываются в пустую строку, даже если заданы, поэтому проект не может тихо отправить ваш ключ Anthropic на свой сервер.
• Доверяйте тому, что сервер возвращает, так же мало, как тому, что он запускает. Документация Anthropic предупреждает, что серверы, получающие внешний контент, могут подвергнуть вас prompt injection. Выбирайте режимы только для чтения и токены с минимальными правами.

Перед одобрением прочитайте command, args и url каждого сервера так же внимательно, как скрипт postinstall. Общая картина — в статье о безопасности ИИ-агентов для программирования.

Если вы работаете не только с Claude Code

Всё описанное выше относится к одному CLI. Codex хранит свои серверы в ~/.codex/config.toml, Gemini CLI — в собственном settings.json, и у каждого инструмента свои команды. Если Claude Code — ваш единственный агент, claude mcp add и закоммиченного .mcp.json вполне достаточно, и ничего здесь не требует другого инструмента.

Если вы запускаете несколько CLI для программирования, списки серверов со временем расходятся. Для этого и сделан MCP-менеджер в AgentVera — десктопном приложении, которое издаёт этот блог:

• Добавлен один раз, подключается при запуске. Вы регистрируете stdio-, HTTP- и SSE-серверы в AgentVera, и они подключаются при старте агентов: ко всем агентам, к выбранным, к агентам группы или к роли в команде. Их получают Claude Code, Codex и другие CLI-агенты с поддержкой MCP.
• В согласии с конфигурацией Claude Code. Серверы из настроек Claude Code и Codex отображаются вместе с их состоянием; их можно импортировать в AgentVera или удалить из CLI, а серверы AgentVera можно записать в настройки CLI.
• Один вход, никаких токенов в файлах. Удалённые серверы идут через шлюз AgentVera, вход на OAuth-сервер выполняется один раз в приложении, и CLI агента не хранит ни заголовков, ни токенов. Секретные переменные окружения и заголовки хранятся в связке ключей операционной системы.
• Видимая стоимость. Проверка подключения показывает инструменты, промпты и ресурсы сервера с примерной стоимостью в токенах для каждого инструмента.

Итог

Начните с одного действительно нужного сервера, добавленного через claude mcp add в самом узком подходящем scope. Проверьте его через claude mcp list или /mcp, войдите через /mcp или claude mcp login, а в закоммиченный .mcp.json переносите его, только когда он нужен всей команде, и с токенами в ссылках ${VAR}. Когда что-то ломается, большую часть проблем решают claude mcp get, MCP_TIMEOUT и MAX_MCP_OUTPUT_TOKENS.

Читайте также:

• Что такое MCP-сервер?
• Лучшие MCP-серверы для агентов программирования
• MCP-менеджер
• Агент Claude Code