MCP-сервер подключает Claude Code к внешнему инструменту, данным или API по открытому протоколу. Это может быть локальная утилита, удалённый HTTP-сервис или сервер, который предоставляет набор операций для проекта. Подключение не означает, что Claude Code автоматически получит безусловный доступ ко всему компьютеру: безопасность определяется транспортом, областью конфигурации, разрешениями и тем, какие инструменты разрешены конкретному запуску.
Что проверить до подключения
Начните с источника сервера. Anthropic прямо рекомендует подключать только доверенные MCP-серверы и отдельно отмечает, что сторонние серверы не управляются и не проходят аудит Anthropic. Изучите репозиторий или страницу поставщика, список инструментов, требуемые переменные, транспорт, права на файлы и способ обновления. Для сервера, который может менять данные, одного красивого README недостаточно.
Сформулируйте минимальную задачу: прочитать документы, создать issue, выполнить запрос к базе или обновить запись. Если достаточно чтения, не выдавайте серверу полномочия на запись. Отдельно определите, какие данные могут попасть в контекст модели, кто увидит результат и можно ли отключить сервер без остановки проекта.
| Вопрос | Проверка | Решение |
|---|---|---|
| Где работает сервер | Локальный процесс или URL | Выбрать stdio, HTTP или SSE |
| Какие данные нужны | Файлы, API, база, задачи | Ограничить область и токены |
| Есть ли запись | Список операций | Разрешать запись отдельно |
| Кому нужен доступ | Один разработчик или команда | Выбрать local, project или user |
Области local, project и user
Claude Code поддерживает несколько областей конфигурации. Локальная область подходит для личного эксперимента в конкретном проекте. Проектная область сохраняется в .mcp.json и предназначена для общего состава серверов команды. Пользовательская область делает сервер доступным в разных проектах пользователя. Выбор области — это решение о распространении доступа, а не просто удобный флаг.
Для сервера с чувствительными переменными начинайте с local. Если команда действительно должна использовать один и тот же сервер, переносите только конфигурацию, а секреты оставляйте во внешнем окружении. Проектный файл не должен содержать реальные токены. Перед тем как принять `.mcp.json` из репозитория, прочитайте его как код: проверьте команду, аргументы, URL, переменные и предполагаемые каталоги.
При совпадении имён конфигурации действует иерархия областей, описанная в документации Claude Code. Чтобы не отлаживать «не тот сервер», используйте уникальные имена и после изменения смотрите итоговый список через CLI.
Локальный stdio-сервер
Локальный stdio-сервер запускается как процесс на вашей машине, а Claude Code общается с ним через стандартные потоки. Учебный пример использует условную команду и не устанавливает сторонний пакет:
claude mcp add --scope local demo-tools -- node ./mcp-server.js
claude mcp list
claude mcp get demo-toolsДвойной дефис отделяет параметры Claude Code от команды и её аргументов. Если серверу нужна переменная, передайте её через --env, но не подставляйте рабочий секрет в историю shell:
claude mcp add --scope local --env SERVICE_TOKEN="$SERVICE_TOKEN" demo-tools -- node ./mcp-server.jsПеред первым вызовом проверьте, что команда запускается в ожидаемом каталоге, зависимость зафиксирована, а вывод ошибки не содержит секрет. Для Windows с локальным npx документация Anthropic отдельно указывает на необходимость оболочки cmd /c в нативной среде Windows; в WSL сценарий отличается. Не переносите команду между системами без проверки.
Удалённый HTTP или SSE-сервер
Удалённый сервер добавляют с указанием транспорта и URL. Учебный пример:
claude mcp add --transport http docs-service https://example.invalid/mcp
claude mcp listДомен example.invalid выбран специально и не является рабочим сервисом. Для реального подключения используйте URL из официальной документации поставщика, проверьте TLS-сертификат, домен и способ аутентификации. OAuth для удалённых серверов запускается из интерфейса /mcp, если сервер его поддерживает. Токен OAuth нельзя переносить в `.mcp.json` или команду, которая попадёт в журнал.
HTTP и SSE дают разные способы обмена событиями, а поддержка зависит от конкретного сервера и версии Claude Code. Если соединение не устанавливается, разделите диагностику: сначала DNS и TLS, затем авторизацию, затем список инструментов, затем вызов простого безопасного метода. Не начинайте проверку с операции записи.
Проверка доступа и инструментов
После добавления используйте claude mcp list и claude mcp get имя. В интерактивном сеансе команда /mcp помогает увидеть состояние подключения и пройти OAuth. Затем попросите Claude Code выполнить безопасную операцию чтения и сравните результат с источником вручную. «Сервер отображается в списке» означает только наличие конфигурации, а не то, что каждый инструмент работает корректно.
Для автоматического запуска можно использовать конфигурационный файл и явный список разрешённых инструментов. Названия инструментов имеют формат, который показывает сервер и операцию. Состав разрешений уточняйте через документацию и фактический список сервера:
claude -p "Прочитай список доступных документов" \
--mcp-config ./mcp-servers.json \
--allowedTools "mcp__docs__list_documents"Это учебный синтаксический пример. Не добавляйте в разрешения неизвестные операции и не используйте режим полного обхода подтверждений в рабочем проекте без изоляции и отдельного обоснования.
Разрешения и границы безопасности
У MCP-сервера есть собственные возможности, а у Claude Code — система разрешений. Эти слои нужно проверять вместе. Сервер файлов может читать больше, чем требуется задаче; API-сервер может создавать записи; сервер базы данных может выполнять запросы с побочными эффектами. Ограничьте каталоги, учётные данные и набор разрешённых инструментов. Для чувствительных репозиториев сначала используйте режим планирования или чтение, затем отдельно подтверждайте изменения.
- Читайте конфигурацию сервера перед добавлением в project scope.
- Храните токены в окружении или менеджере секретов.
- Не разрешайте запись, если нужна только аналитика.
- Проверяйте предлагаемые Claude Code команды и изменения.
- Не передавайте MCP-серверу персональные или производственные данные без основания.
- Отдельно контролируйте сетевой выход локального процесса.
Проектный .mcp.json может вызвать подтверждение перед использованием. Это полезная граница: участник команды видит, что репозиторий предлагает подключить внешний процесс. Не отключайте подтверждение механически, пока не поняли происхождение файла и состав разрешений.
Диагностика типовых ошибок
| Симптом | Вероятная причина | Проверка |
|---|---|---|
| Сервер не виден | Неверная область или JSON | claude mcp list и просмотр файла |
| Connection closed | Команда или оболочка не подходят ОС | Запустить сервер вручную и проверить wrapper |
| 401/403 | Нет токена или недостаточно прав | Проверить OAuth/переменную без вывода значения |
| Инструмент недоступен | Он не разрешён в запуске | Сверить --allowedTools и имя операции |
Если локальный процесс завершается, запустите ту же команду вне Claude Code с тестовыми данными и посмотрите код завершения. Если удалённый сервис отвечает ошибкой авторизации, перевыпустите или переподключите токен через предусмотренный интерфейс, а не добавляйте секрет в URL. Если ответ слишком большой, уменьшите запрос: Claude Code предупреждает о крупных результатах MCP, а увеличение лимита не делает чрезмерный объём безопасным или полезным.
Удалить подключение можно командой claude mcp remove имя. После удаления проверьте список и связанные файлы. Для OAuth используйте очистку авторизации в интерфейсе /mcp, если нужно отозвать сохранённый доступ. Удаление локальной записи не обязательно отзывает токен у внешнего провайдера — это отдельный шаг.
Чек-лист перед командным использованием
- У поставщика есть понятное описание кода, инструментов и требуемых прав.
- Вы выбрали минимальный транспорт и область конфигурации.
- В проектном файле нет настоящих ключей и токенов.
- Сделан безопасный read-only тест и проверен его результат.
- Операции записи требуют отдельного подтверждения.
- Сетевые адреса, TLS и OAuth проверены вне слепого копирования команды.
- В CI разрешён только нужный набор MCP-инструментов.
- Есть инструкция отключить сервер и отозвать внешний токен.
Подключение MCP-сервера — это не установка «ещё одного плагина», а добавление нового доверенного контура между моделью, инструментом и данными. Надёжный порядок прост: изучить сервер, выбрать область, подключить с минимальными правами, проверить безопасным чтением, затем постепенно разрешать операции. Такой подход позволяет получить пользу от MCP и сохранить возможность быстро остановить интеграцию при ошибке.
Как оформить конфигурацию для команды
Командная конфигурация должна объяснять не только команду подключения, но и границы использования. Рядом с `.mcp.json` зафиксируйте назначение сервера, владельца, допустимые окружения, список операций чтения и порядок запроса записи. Секреты при этом остаются вне файла: участник команды получает их через утверждённый менеджер секретов, а локальная машина подставляет значения во время запуска.
Не копируйте в общий репозиторий абсолютные пути конкретного ноутбука, личные токены и временные каталоги. Используйте переменные окружения и проверяйте, что шаблон конфигурации запускается на чистом тестовом окружении. Если сервер нужен только одному человеку, local scope безопаснее project scope. Если он нужен всем, согласуйте изменение как зависимость проекта и проведите ревью конфигурации.
Перед обновлением версии сервера сохраните перечень доступных инструментов и выполните тестовый запуск. Новая версия может добавить операцию записи, изменить формат ответа или расширить требуемые права. Это не означает, что обновление опасно, но означает, что его нужно принимать как изменение кода. Для удалённого сервиса дополнительно проверьте домен, сертификат, политику OAuth и возможность отозвать токен.
Полезная учебная практика — завести тестовый сервер с одним безопасным методом, подключить его в local scope, проверить видимость, затем удалить. После этого повторить процесс в project scope уже с ревью файла. Так команда проверяет не только синтаксис, но и весь жизненный цикл: добавить, подтвердить, использовать, обновить и отключить.
Отдельно договоритесь о формате инцидента. Если MCP-сервер неожиданно запросил доступ к другому каталогу, начал возвращать чувствительные данные или перестал соответствовать описанию, остановите сеанс, удалите подключение и отзовите внешний токен. Не исправляйте подозрительное поведение разрешением всех инструментов. Сохраните безопасные диагностические сведения: имя сервера, область, версию, время и код ошибки, но не копируйте секреты и персональные данные.
Для больших команд полезно иметь небольшой каталог разрешённых серверов с владельцем и датой последнего ревью. Такой каталог не заменяет проверку каждой версии, но помогает не подключать случайный пакет из поисковой выдачи. В проектной документации укажите, какие операции считаются чтением, какие меняют состояние и кто подтверждает изменения. Чем ближе сервер к production-данным, тем строже должен быть этот процесс.
Не забывайте проверять результат, а не только соединение. Безопасный тест должен показать имя сервера, доступный инструмент и ожидаемый ответ на ограниченном наборе данных. Если модель сделала вывод, сверяйте его с исходным сервисом. MCP упрощает передачу контекста, но не отменяет обычные правила валидации, резервного копирования и контроля изменений.
Повторяйте этот тест после обновления конфигурации, версии сервера или прав доступа.
Результат теста храните рядом с задачей, но без токенов и приватных ответов. Так проще увидеть регрессию после обновления.