Настройка MCP-сервера в Claude Code: шаг за шагом

Castel Studio, Ницца · Опубликовано 14 октября 2026 г.

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

Это руководство основано на официальной документации MCP для Claude Code. Мы в нашей студии подключаем MCP-серверы к Claude Code каждый день, и приведенные ниже ошибки — это именно то, с чем мы чаще всего сталкиваемся в проектах клиентов.

Перед добавлением сервера: три вопроса

Кому он нужен? Только вам, всем участникам проекта или вам во всех проектах. Ответ определяет скоуп (scope) и место хранения конфигурации.
К чему он имеет доступ? Сервер, который только читает данные из трекера задач, несет меньше рисков, чем тот, который может писать в базу данных или отправлять почту. Если сервис позволяет, начинайте с режима только для чтения.
Где хранятся ключи? Определитесь до ввода первой команды. Токен, случайно прописанный в общий файл — это самая сложная ошибка для исправления, так как он навсегда остается в истории репозитория.

Три способа добавления сервера

Удаленный сервер по HTTP — стандартный выбор для облачных сервисов:

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"

Локальный сервер через stdio запускается как программа на вашем компьютере:

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Двойной дефис (--) здесь очень важен. Все, что идет до него, предназначено для Claude Code; все, что после — это команда самого сервера, которая передается без изменений.

SSE по-прежнему работает, но устарел. По возможности отдавайте предпочтение HTTP.

Скоупы: кто видит сервер

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

Скоуп	Где применяется	Совместный доступ для команды	Где сохраняется
local (по умолчанию)	этот проект, только вы	нет	`~/.claude.json`
project	этот проект	да, через репозиторий	`.mcp.json` в корне проекта
user	все ваши проекты	нет	`~/.claude.json`

Выберите нужный вариант с помощью параметра --scope:

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

Если сервер с одинаковым именем задан в нескольких скоупах, приоритет имеет локальный, затем проектный и в последнюю очередь пользовательский. Выигрывающая запись используется целиком; слияние полей не происходит.

Командный файл .mcp.json без секретов

Проектный скоуп создает файл, который можно коммитить в репозиторий. Избавьтесь от ключей в нем с помощью переменных окружения:

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

Конструкция ${VAR} заменяется на значение переменной, а ${VAR:-default} подставляет значение по умолчанию. Если у переменной нет ни значения, ни дефолта, Claude Code выдает предупреждение и оставляет текст как есть, поэтому незаполненный ключ проявится в виде ошибки подключения, а не тихого сбоя.

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

Проверка работоспособности MCP-сервера

claude mcp list
claude mcp get notion

Команда claude mcp list показывает статус каждого сервера: подключен, требует аутентификации или ошибка подключения. Внутри сессии команда /mcp отображает ту же информацию и позволяет войти в удаленные серверы, использующие OAuth. Чтобы удалить сервер, используйте claude mcp remove notion.

Частые проблемы

Сервер работает только у вас. Он был добавлен с локальным скоупом по умолчанию. Добавьте его заново с флагом --scope project.
Ключ попал в репозиторий. Кто-то вставил токен прямо в .mcp.json. Отозвите ключ и перейдите на использование формата ${API_KEY}.
Инструменты видны, но не разрешены к использованию. Правила разрешений и шаблоны хуков используют полные имена инструментов: mcp__server__tool. Шаблон вида mcp__memory ничего не сопоставит; подробнее читайте в нашей статье про хуки в Claude Code.
Слишком большие ответы. Claude Code предупреждает, когда результат работы инструмента превышает 10 000 токенов, и жестко ограничивает его на отметке 25 000 токенов по умолчанию (лимит можно изменить через MAX_MCP_OUTPUT_TOKENS). Инструмент, который каждый раз возвращает всю таблицу целиком, требует фильтрации на стороне сервера, а не увеличения лимитов.
Непроверенный сервер. Серверы, запрашивающие внешние данные, могут принести в вашу сессию инъекцию промптов (prompt injection). Подключайте только те серверы, которым доверяете, и давайте им ровно столько прав, сколько требует задача.

Если вы решаете, где именно должна быть реализована логика — в MCP-сервере, скилле или субагенте, наша статья про агентов и скиллы поможет разобраться в разнице.

Когда стоит передать эту работу специалистам

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

Вопросы

Почему мои коллеги не видят добавленный мной MCP-сервер?

Потому что по умолчанию используется локальный скоуп (local): сервер сохраняется только в вашем ~/.claude.json для этого проекта. Добавьте его с флагом --scope project, чтобы запись попала в .mcp.json в репозитории, который сможет закоммитить вся команда.

Куда поместить API-ключи для MCP-сервера?

Не в сам .mcp.json. Напишите ${API_KEY} в полях url, headers, command, args или env, а само значение храните в переменной окружения. Конструкция ${VAR:-default} позволяет задать резервное значение.

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

Сначала проверьте его статус через claude mcp list: возможно, требуется аутентификация или произошел сбой подключения. Затем проверьте имена инструментов в правилах разрешений и хуках: они используют формат mcp__server__tool.

Поддерживается ли SSE до сих пор?

Он по-прежнему работает, но устарел (deprecated). Используйте HTTP-транспорт, если сервис его поддерживает; новые версии сначала пытаются работать по HTTP и при необходимости самостоятельно откатываются к SSE.