Подключение MCP-серверов в Claude Code и рабочие процессы

Суть

Проектный .mcp.json — под версионным контролем, общий для команды; пользовательский ~/.claude.json — личный, никогда не шарится. Конфигурации складываются аддитивно, но личная не попадает в репозиторий.

Секреты и описания

Никогда не хардкодьте токены в .mcp.json — используйте синтаксис ${ENV_VAR}, раскрываемый из окружения во время запуска. Описания MCP-инструментов конкурируют со встроенными (Grep, Bash): усильте описание, явно объяснив, что MCP-инструмент даёт сверх встроенных. MCP-ресурсы дают агенту каталог контента при старте, снижая число разведывательных вызовов.

Проектный .mcp.json с безопасным управлением секретами

{
  "mcpServers": {
    "github": {
      "type": "url",
      "url": "https://github.mcp.example.com/sse",
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "jira": {
      "type": "url",
      "url": "https://jira.mcp.example.com/sse",
      "env": { "JIRA_API_KEY": "${JIRA_API_KEY}" }
    }
  }
}

Anti-patterns

Ловушка	Почему не работает	Верный паттерн
Класть командные MCP-серверы в `~/.claude.json`	Личный конфиг не шарится через VCS — у коллег сервера нет	Командные — в `.mcp.json`, закоммиченный в репозиторий
Хардкодить токены в `.mcp.json`	Секреты в системе контроля версий — серьёзная брешь	Раскрытие `${ENV_VAR}`; переменная в окружении, не в файле
Писать свой MCP-сервер для Jira	У Jira есть community-сервер — своя реализация это трата сил и бремя поддержки	Community-серверы для стандартных интеграций; своё — лишь под уникальное
Оставлять описания MCP-инструментов минимальными	Claude предпочтёт знакомые Grep/Bash слабо описанным MCP	Усилить описание: что MCP даёт сверх встроенных

Exam traps

Ловушка	Почему не работает	Верный паттерн
Считать `.mcp.json` и `~/.claude.json` равнозначными	Личный конфиг не шарится; командным нужен проектный уровень	Общее — в `.mcp.json`; личное/экспериментальное — в `~/.claude.json`
Ждать выбора MCP над встроенным без усиленного описания	«Searches the codebase» неотличимо от Grep — модель берёт привычное	Описать уникальные возможности (покрытие, графы зависимостей, частота)

Практическое задание (T4)

Написать .mcp.json с GitHub (community) и командным сервером документации — оба токена через ${ENV_VAR}.
Добавить запись в ~/.claude.json для личного экспериментального сервера и объяснить, почему здесь, а не в .mcp.json.
Написать усиленные описания обоих MCP-инструментов: что они дают сверх Grep и Bash.
Спроектировать MCP-ресурс с иерархией документации; описать каталог и как он снижает разведку.
Найти описания, способные столкнуться со встроенными инструментами, и устранить коллизии.

Проверка знаний

Продуктивность разработчика с Claude

Ведущий разработчик настроил общий GitHub MCP-сервер. Новый разработчик клонирует проект — инструментов GitHub MCP нет вовсе. Ведущий настраивал на своей машине. Вероятная причина?

A Сервер настроен в ~/.claude.json только на машине ведущего — личный конфиг не шарится через VCS
B Сервер должен быть в .mcp.json в корне проекта — тогда доступен всем при клоне
C Сервер надо описать в CLAUDE.md, чтобы он грузился с прочей конфигурацией
D Каждый разработчик ставит MCP-сервер вручную — общего механизма нет

Продуктивность разработчика с Claude

Агент упорно берёт встроенный Grep вместо MCP-сервера search_codebase с более богатыми результатами (покрытие тестами, графы зависимостей, частота использования). Описание MCP: «Searches the codebase». Лучшее решение?

A Система-промпт: «всегда предпочитай MCP search_codebase встроенному Grep»
B Убрать встроенный Grep из доступных инструментов агента
C Усилить описание MCP: явно объяснить богатые возможности (покрытие, графы, частота) и указать форматы входа
D Перенести MCP-сервер из .mcp.json в ~/.claude.json для повышения приоритета

Продуктивность разработчика с Claude

Команда использует 3 MCP-сервера: GitHub и Linear в проектном .mcp.json; Datadog — в пользовательском ~/.claude.json. У нового разработчика GitHub и Linear работают, Datadog отсутствует. Вероятная причина?

A Пользовательский конфиг перекрыт проектным .mcp.json — перенести Datadog в .mcp.json
B Пользовательские MCP-серверы привязаны к домашней папке и недоступны в подпапках проекта
C Datadog настроен в ~/.claude.json исходного разработчика — файл не шарится через VCS, на машине новичка его нет
D Истекли учётные данные Datadog — нужно повторно аутентифицироваться