MCP Claude Code: как дать агенту доступ к нужному инструменту

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

Команды и области настройки ниже сверены с официальной документацией Claude Code по MCP 25.10.2026. Названия параметров могут измениться; перед вводом команды сверьте её с документацией своей версии. Официально Россия не в списке поддерживаемых стран; как это решают на практике, разбираю на встрече по обучению.

Когда MCP действительно нужен

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

Опишите одну операцию: «найди задачу по номеру и верни заголовок, статус, описание». Затем перечислите, какие поля допустимы и кто имеет право их видеть. Запись комментария, смена статуса и удаление задачи требуют отдельных прав. Не выдавайте серверу максимальный токен для проверки чтения одной карточки. Чем меньше поверхность действия, тем проще объяснить пользователю результат и восстановить причину ошибки.

Локальный и удалённый сервер

Локальный MCP‑сервер запускается как процесс рядом с Claude Code и общается через стандартные потоки. Это удобно для инструментов на вашем компьютере. Удалённый сервер доступен по сетевому адресу, например по HTTPS; для него нужны проверка адреса и способ входа. Выбор зависит от того, где живут данные и кто обслуживает соединение. Папка проекта сама по себе не становится безопасной только из‑за локального процесса: его права нужно ограничить.

В официальной документации есть команды claude mcp add для локального запуска и удалённого HTTP-сервера. В примере ниже адрес и имя вымышлены. Не запускайте команду с чужим сервером, пока не проверили владельца, запрашиваемые права и способ хранения токена. Для проектной команды заранее решите, будет ли конфигурация общей для команды или личной.

# Удалённый сервер: замените адрес только после проверки владельца.
claude mcp add --transport http example https://mcp.example.com/mcp

# Посмотреть список и состояние подключений.
claude mcp list
claude mcp get example

Для локального сервера команда помещается после --, чтобы её параметры передались запускаемому процессу. Ниже показана форма записи с вымышленным именем сервера. Возьмите точную команду из инструкции к выбранному серверу и проверьте её перед исполнением.

claude mcp add local-example -- your-local-server --read-only

Как проверять подключение без записи в систему

После добавления посмотрите claude mcp list и состояние через /mcp внутри Claude Code. Запись об успешном добавлении конфигурации ещё не означает, что сервер доступен и авторизация завершена. Начните с безопасного чтения известной задачи или документа. Попросите вернуть точный идентификатор и одно поле, которое можно сверить вручную. Если результат пустой, уточните область доступа и параметры вызова до попытки записать что‑либо.

Затем проверьте отказ. Попросите прочитать запись, на которую токен не должен иметь права, и убедитесь, что ошибка не раскрывает содержимое. Для действия записи сначала используйте тестовый объект или черновик. Сверьте, не создан ли он дважды после повторного вызова. Если сервер поддерживает только широкие права, его нужно изолировать по учётной записи и ограничить операции на стороне вашего приложения.

Что делать с секретами и конфигурацией

Не вставляйте токен в команду, скриншот или Markdown-статью. Секрет хранится в предназначенной для него среде и передаётся серверу способом, который описал владелец сервиса. Проектную конфигурацию можно сделать общей, но согласуйте, какие адреса и права она раскрывает. Перед добавлением файла в Git просмотрите diff и убедитесь, что внутри нет ключей или персональных данных.

Права на стороне MCP‑сервера важнее текста просьбы в чате. Даже если агенту написали «не удалять», техническая возможность удаления остаётся риском. Для чтения задач используйте учётную запись только на чтение; создание и изменение разрешайте отдельным инструментом. Записывайте, какой инструмент был вызван, какой объект затронут и что вернул сервер. Это помогает разобрать и ошибку, и неожиданный результат.

git diff -- .mcp.json
rg -n 'token|secret|password|api.?key' .mcp.json

Если .mcp.json ещё нет, rg сообщит об отсутствии файла: это обычный результат проверки отсутствующего файла.

Как отличить проблему сервера от проблемы ответа модели

Сначала проверьте факт соединения: сервер виден, авторизация завершена, инструмент доступен. Затем вызовите его на известной записи и сверяйте исходный результат. Если результат верный, но ответ помощника неверно его пересказал, исправлять нужно инструкцию и проверку вывода. Если инструмент вернул старые данные, ищите источник, кеш или права на сервере. Один текст «MCP не работает» скрывает разные места сбоя.

Если после подключения Claude Code видит слишком много инструментов, уменьшите набор. Чем яснее названия и описания доступных операций, тем проще агенту выбрать подходящую. На обучении я показываю подключение внешних данных вместе с проверкой результата. Устройство расширений описано в статье про Skills.

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

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

Частые вопросы

MCP‑сервер хранит данные проекта?

Не обязательно. Он предоставляет инструменты для чтения или действия; данные могут оставаться в исходном сервисе. Уточняйте это у конкретного сервера.

Почему подключение видно, а инструмент не отвечает?

Конфигурация могла сохраниться, но сервер недоступен или требует входа. Проверьте статус через claude mcp list и /mcp.

Можно ли подключить сервер только для чтения?

Да, если сервер и учётная запись позволяют ограничить права. Проверяйте техническое ограничение на стороне сервера и учётной записи.

Что лучше для постоянных правил проекта: MCP или файл?

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

Как проверить, что агент использовал нужный источник?

Сравните идентификатор и версию записи с исходным сервисом, а также журнал вызова инструмента. Итоговая фраза без источника недостаточна.