MCP: подключаем внешние инструменты

Встроенные инструменты Claude Code — файлы, поиск, оболочка, веб. Всё остальное — задачи в трекере, записи в базе, страницы в вики — подключается через MCP (Model Context Protocol, протокол контекста модели). Если вы ещё не знакомы с протоколом, начните с урока «Что такое MCP и зачем он нужен» — там разобраны роли хоста, клиента и сервера. Здесь — практическая сторона: как подключить сервер к Claude Code и что с ним потом происходит.

Как это выглядит в Claude Code

Claude Code — хост. Каждый подключённый MCP-сервер даёт ему набор инструментов, и модель вызывает их так же, как встроенные: увидела в запросе «создай задачу в трекере», нашла инструмент «создать задачу», вызвала. Разрешение на вызов спрашивается по тем же правилам, что и для остальных инструментов.

Пример из практики. Тестировщик подключил сервер трекера и пишет: «воспроизведи баг PROJ-1432 и предложи исправление». Claude Code вызывает инструмент получения задачи, читает описание и шаги, находит код, воспроизводит и предлагает патч. Без MCP ту же информацию пришлось бы копировать в чат руками.

Серверы бывают двух видов по способу подключения. Удалённые (HTTP) работают где-то в сети: официальные серверы Notion, Sentry, GitHub, Stripe и других сервисов. Локальные (stdio) — процесс на вашей машине, который Claude Code запускает сам: сервер файловой системы, сервер базы данных, ваш собственный скрипт.

Команда claude mcp add

Удалённый сервер по HTTP:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

Локальный сервер, который запускается командой:

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@localhost:5432/shop"

Обратите внимание на --: всё после него передаётся серверу как есть, а не разбирается Claude Code. Переменные окружения для локального сервера задаются флагом --env KEY=value до --.

Если сервер описан в документации как JSON-конфигурация, её можно передать целиком:

claude mcp add-json weather '{"type":"http","url":"https://api.weather.com/mcp"}'

Управление: claude mcp list показывает подключённые серверы и их статус, claude mcp get <имя> — подробности, claude mcp remove <имя> удаляет. Внутри сессии команда /mcp показывает состояние серверов, позволяет включать и отключать их и проходить авторизацию.

Области видимости

Флаг --scope задаёт, где хранится конфигурация и кто её видит.

• local (по умолчанию) — только для вас и только в этом проекте. Хранится в ~/.claude.json. Подходит для экспериментов и серверов с личными ключами.
• project — в файле .mcp.json в корне проекта, идёт в git. Для серверов, которые нужны всей команде: трекер, база staging, сервер документации.
• user — для вас во всех проектах. Личные утилиты, которые вы используете везде.

Файл .mcp.json для проектной области выглядит так:

{
  "mcpServers": {
    "tracker": {
      "type": "http",
      "url": "https://mcp.tracker.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TRACKER_TOKEN}"
      }
    },
    "db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DB_URL}"]
    }
  }
}

Секреты в файл не пишут — только ссылки на переменные окружения вида ${VAR} или ${VAR:-значение по умолчанию}. Это правило из нашего CLAUDE.md для админок применимо и здесь: токен живёт у разработчика в окружении, а в git уходит только имя переменной. При первом запуске в проекте с .mcp.json Claude Code спросит, доверяете ли вы этим серверам, — это защита от репозиториев, которые могли бы запустить на вашей машине что угодно. Сбросить выбор можно командой claude mcp reset-project-choices.

Если один сервер описан в нескольких областях, побеждает более локальная: local над project, project над user.

Авторизация

Многие удалённые серверы используют OAuth. Подключаете сервер без ключа, затем в сессии набираете /mcp, выбираете сервер и проходите вход в браузере:

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

Из терминала то же самое делает claude mcp login <имя>. Токены хранятся в системном хранилище учётных данных и обновляются сами. Для серверов с готовыми ключами используется заголовок --header, как в примере с GitHub выше.

Ресурсы и промпты

Кроме инструментов сервер может отдавать ресурсы — данные для чтения. В Claude Code они подключаются через @ с именем сервера: покажи данные из @github:repos/owner/repo/issues. Автодополнение после @ перечисляет доступные ресурсы.

Промпты сервера — готовые шаблоны — появляются в меню / как команды с именем сервера в названии (в документации формат описан как /mcp__сервер__промпт). Так сервер трекера может дать команду «подготовить релиз-ноты по задачам спринта».

Что MCP стоит по контексту

Каждый сервер добавляет в контекст свои инструменты. По умолчанию Claude Code откладывает загрузку полных описаний: при старте в окно попадают только имена инструментов и инструкции сервера, а схема конкретного инструмента подгружается, когда модель решает его использовать. Это называется tool search и включено по умолчанию. Тем не менее десяток серверов «на всякий случай» — плохая идея: /context покажет, сколько они занимают, а /mcp позволит отключить лишние для текущего проекта.

Вывод инструмента ограничен: по умолчанию до 25 000 токенов на один ответ, с предупреждением после 10 000. Если сервер отдаёт больше — например, полную схему базы, — результат обрежется. Порог задаётся переменной MAX_MCP_OUTPUT_TOKENS.

Документация даёт неожиданный на первый взгляд совет: для сервисов с хорошим CLI — GitHub (gh), AWS, Google Cloud, Sentry — утилита командной строки экономнее MCP-сервера. Она не добавляет в контекст список инструментов, а Claude умеет ей пользоваться. MCP выигрывает там, где CLI нет или где нужны ресурсы и промпты.

Безопасность

Сервер, который умеет удалять записи, будет их удалять, если модель это вызовет. Три правила:

• Для баз данных — пользователь только на чтение. В примере выше не случайно readonly.
• Инструменты MCP подчиняются правилам прав. Имя инструмента для правил — mcp__<сервер>__<инструмент>: правило deny для mcp__db__execute заблокирует выполнение произвольного SQL при любом режиме. Шаблон mcp__db__* покрывает все инструменты сервера.
• Не подключайте серверы из непроверенных источников. Сервер — это код, который получает ваши токены и выполняется на вашей машине или от вашего имени.

Для команды разумная схема: серверы, нужные всем, — в .mcp.json под ревью, с секретами через переменные; личные эксперименты — в local.