MCP в Claude Code: как правильно добавлять серверы
Подключаем Context7, Playwright или любой MCP-сервер к Claude Code — транспорты, scope, файл .mcp.json, API-ключи и панель /mcp в одном иллюстрированном разборе.
Коротко
- Любой сервер ставится одной командой: claude mcp add name -- npx -y @scope/package для локальных или claude mcp add --transport http name url для удалённых.
- Транспорта три: stdio запускает команду на вашей машине, SSE — устаревший удалённый вариант, streamable HTTP — современная замена.
- Три scope решают, кому достанется сервер: local (только вам), project (общий через .mcp.json) и user (во всех ваших проектах).
- Введите /mcp внутри сессии, чтобы увидеть статус и инструменты; первый вызов инструмента запрашивает разрешение — можно разрешить один раз или навсегда.
Claude Code Tutorial #7 - MCP Servers
Канал: The Net Ninja14:16
Claude Code MCP: How to Add MCP Servers (Complete Guide)
Канал: Leon van Zyl17:58
Model Context Protocol (MCP) — official Claude Code docs
Документация: code.claude.com/docs
Скриншоты взяты из главы The Net Ninja — чистая запись во весь экран. Разбор команд, scope и исправления для Windows опираются на более подробный разбор Leon van Zyl и официальную документацию.
Права на кадры принадлежат их авторам; здесь они указаны с глубокими ссылками на нужные моменты. Текст — наш.
С нуля до двух работающих MCP-серверов
Часть 1 · Что дают MCP-серверы
- 1
Что MCP даёт Claude Code
В Claude Code встроены инструменты для файлов и терминала, но всё за пределами кодовой базы ему недоступно. MCP (Model Context Protocol) — стандартный способ Anthropic подключать дополнительные инструменты: сервер открывает свои возможности, а Claude Code вызывает их как обычные встроенные инструменты.
Слайд курса, где MCP определён одной строкой.Смотреть с 0:52 - 2
Выбирайте серверы под задачу
У каждого сервера свои инструменты. Сервер Supabase умеет показывать таблицы, деплоить edge-функции и выполнять SQL; Playwright управляет настоящим браузером; Context7 выдаёт актуальную документацию фреймворков. Начните с того, который убирает вашу самую частую рутину.
Пример с Supabase: три инструмента, один внешний сервис.Смотреть с 1:24 - 3
Ищите команду установки в README сервера
Авторы серверов публикуют готовую команду для Claude Code прямо в README — Context7 и Playwright не исключение. Посмотреть, что вообще есть, удобнее всего в каталогах вроде PulseMCP.
README Playwright MCP описывает возможности и требования.Смотреть с 2:02 - 4
Разберитесь с тремя транспортами
Официальная документация делит установку на локальную и удалённую. stdio-сервер запускает команду на вашей машине — это вариант по умолчанию. SSE и HTTP-серверы — удалённые эндпоинты; SSE устарел, его сменил streamable HTTP. Синтаксис claude mcp add для каждого немного отличается.
Страница документации, сравнивающая локальный stdio с удалёнными SSE и HTTP.Смотреть с 3:02
Часть 2 · Добавляем первый сервер
- 5
Добавьте Context7 со scope project
В терминале: claude mcp add context7 --scope project -- npx -y @upstash/context7-mcp. Имя выбираете вы, всё после двойного дефиса — команда запуска, а --scope project записывает сервер в общий конфиг проекта, а не в ваш личный.
Точная команда добавления сервера документации Context7.Смотреть с 5:22 - 6
Прочитайте созданный .mcp.json
Серверы со scope project попадают в файл .mcp.json в корне репозитория, под ключом mcpServers. Каждая запись хранит тип — здесь stdio — плюс команду и её аргументы: тот же формат, что используют Cursor и Claude Desktop.
Внутри .mcp.json: type, command и args для stdio-сервера.Смотреть с 6:42 - 7
Windows: не забудьте префикс cmd /c
На нативной Windows без WSL перед npx в stdio-командах нужен cmd /c, чтобы оболочка корректно закрывалась после работы сервера. Документация выделяет это в предупреждение, а в видеоразборе показано, что именно править.
Официальное предупреждение для stdio-серверов на Windows.Смотреть с 3:24 - 8
Убедитесь, что файл попал в репозиторий
После добавления со scope project файл .mcp.json появляется в проводнике как новый неотслеживаемый — закоммитьте его, и коллеги получат те же серверы. Серверы со scope local этот файл никогда не трогают.
Новый .mcp.json в корне проекта: ещё не отслеживается, готов к коммиту.Смотреть с 8:32 - 9
Предпочитаете удалённое? Берите HTTP
Когда локальный stdio капризничает, быстрый выход — удалённый эндпоинт: claude mcp add --transport http context7 --scope project https://mcp.context7.com/mcp. Ни локального процесса, ни npm — Claude Code обращается к URL напрямую.
HTTP-вариант команды добавления для эндпоинта Context7.Смотреть с 8:36 - 10
Проверьте подключение в /mcp
Запустите Claude Code и введите /mcp. У каждого сервера видны статус и список инструментов. Сбой обычно лечится встроенным переподключением; если нет — ниже раздел о типовых причинах.
Панель /mcp: context7 подключён, видны его два инструмента.Смотреть с 9:22
Часть 3 · Серверы в реальной работе
- 11
Вызовите сервер реальным запросом
Попросите то, чего встроенные инструменты не умеют, и назовите сервер: «сверь мой глобальный CSS с актуальной документацией Tailwind — используй context7». Упоминание файла через @ привязывает ответ к вашему коду.
Промпт, запрашивающий актуальную документацию Tailwind через context7.Смотреть с 9:38 - 12
Одобрите вызов инструмента
При первом запуске инструмента сервера Claude Code спросит разрешение. Одобрите один раз или выберите «всегда разрешать» для серверов, которым доверяете, — дальше вызовы пойдут без вопросов.
Карточка разрешения для инструмента resolve-library-id у Context7.Смотреть с 10:00 - 13
Прочитайте ответ с опорой на документацию
Инструмент возвращает нужные разделы — здесь руководство по переменным темы Tailwind v4 — с показанной стоимостью в токенах, а Claude Code применяет их к вашему файлу. В этом весь смысл: ответы из актуальной документации вместо догадок из обучающих данных.
Ответ get-library-docs, подтверждающий настройку темы.Смотреть с 10:15 - 14
Закрепите привычку в CLAUDE.md
Введите символ решётки, чтобы добавить память проекта, например: «при работе с новыми библиотеками и фреймворками сверяйся с актуальной документацией через Context7». Строка попадёт в CLAUDE.md, и все следующие сессии её унаследуют.
Однострочная память в CLAUDE.md, делающая Context7 дефолтом.Смотреть с 10:42 - 15
Второй сервер: Playwright
Для браузерной автоматизации повторяем шаблон: claude mcp add playwright --scope project -- cmd /c npx @playwright/mcp@latest — на macOS и Linux часть cmd /c убирается. Один репозиторий, несколько серверов, один файл конфигурации.
Добавление Playwright MCP со scope project.Смотреть с 11:22 - 16
Смотрите, как он водит браузер
Попросите Claude Code открыть страницу и пересказать её — Playwright переходит, кликает и читает, затем докладывает результат. С документацией Context7 и браузером Playwright большая часть внешних дел — в одном промпте от вас.
Playwright MCP переходит на сайт, чтобы сделать пересказ.Смотреть с 12:42
Переменные окружения, заголовки и API-ключи
Удалённым серверам и API с авторизацией нужны учётные данные. Claude Code принимает их как переменные окружения для stdio-серверов и заголовки для удалённых — править конфиг вручную не нужно.
- 1stdio-серверы: claude mcp add myserver -e API_KEY=your-key -e ZONE=your-zone -- npx -y @some/mcp-server — повторяйте флаг -e для каждой переменной, ставя его сразу после имени сервера.
- 2Удалённые HTTP-серверы: claude mcp add --transport http myserver https://example.com/mcp --header "Authorization: Bearer your-key" — заголовок отправляется с каждым вызовом инструмента.
- 3Напоминание про scope: local оставляет сервер вам в рамках проекта, project делится им через .mcp.json, user ставит его во все ваши проекты. Задаётся флагом -s или --scope при добавлении.
- 4Удаление сервера: claude mcp remove name — для scope project закоммитьте изменение .mcp.json, чтобы сервер пропал и у коллег.
Значения, переданные через -e, хранятся в конфиге открытым текстом. Где API позволяет, берите ключи с узкими правами и никогда не коммитьте реальные учётные данные в project-scope .mcp.json.
Когда /mcp показывает failed
Почти все сбои MCP в Claude Code сводятся к нескольким причинам. Пройдитесь по списку, прежде чем удалять и добавлять заново.
- 1Unknown option -y на Windows: некоторые терминалы спотыкаются об этот флаг npm. Запустите команду добавления из PowerShell или командной строки, либо уберите -y, добавьте сервер, а затем верните -y в массив args в .mcp.json вручную.
- 2stdio падает на нативной Windows: добавьте к команде префикс cmd /c — например cmd /c npx -y @some/package@latest. Без WSL это обязательно, а тег @latest спасает от устаревших кэшированных сборок.
- 3Статус failed: откройте /mcp и переподключитесь — временные сбои обычно уходят со второй попытки. Если нет, панель покажет путь к логу сервера с настоящей ошибкой.
- 4Сервера нет в другом проекте: это scope, работающий как задумано. Серверы со scope project живут в .mcp.json конкретного репозитория; для установки на всю машину берите scope user.
- 5Сервер подключён, но не используется: назовите его в промпте — «проверь документацию через context7» — или добавьте память в CLAUDE.md: без указания модели тянутся к привычным встроенным инструментам.
Если не помогло ничего: claude mcp remove name, перезапустите терминал и добавьте сервер через транспорт, который точно работает — удалённый HTTP самый предсказуемый.