Как подключить MCP-сервер — одной командой, без правки JSON

Большинство инструкций по MCP начинаются со слов «откройте конфигурационный файл и добавьте туда JSON». После этого половина людей закрывает вкладку.

Хорошая новость: так уже давно не нужно. Подключение MCP-сервера — это одна команда в терминале, а JSON редактор пишет за тебя.

Разберём на живом примере. Если ещё не понял, что такое MCP и зачем он — сначала туда, тут будет только практика.

1. Пойми, какой у тебя сервер

Серверов ровно два вида, и от этого зависит команда.

• По ссылке (hosted). Кто-то уже запустил его у себя, тебе дали URL. Ничего ставить не надо.
• Локальный (stdio). Программа, которую агент запускает у тебя на машине. Нужна, когда инструменту нужен доступ к твоим файлам, браузеру или базе.

Посмотри в документацию сервера: если там URL вида https://…/mcp — первый тип. Если строчка вроде npx -y какой-то-пакет — второй.

2. Добавь сервер

Команды выполняй в обычном терминале, а не внутри сессии агента: ты настраиваешь инструмент до разговора.

Для сервера по ссылке:

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

Разбор по частям:

• claude mcp add — регистрируем сервер;
• --transport http — он живёт по URL, а не запускается у тебя;
• claude-code-docs — имя, которое ты придумал сам. По нему сервер будет виден в списке и в выводе агента;
• дальше — сам адрес.

Для локального сервера:

claude mcp add playwright -- npx -y @playwright/mcp@latest

Два отличия. Флага --transport нет — локальные серверы работают по умолчанию. И главное: всё после -- — это команда запуска. Разделитель обязателен, без него аргументы разъедутся.

Этот пример даёт агенту настоящий браузер: открывать страницы, кликать, читать. Аккаунт не нужен, только Node.js 18+.

3. Проверь связь — это не формальность

Сообщение «Added…» значит только, что запись сохранилась. Оно не значит, что сервер работает. Проверяем:

claude mcp list

Что ты увидишь рядом с именем:

• ✔ Connected — всё, можно пользоваться.
• ✘ Failed to connect — сервер не ответил. Для локального это нормально на первом запуске: npx ещё качает пакет. Подожди полминуты и повтори.
• ! Needs authentication — сервер жив, но нужен вход. Либо браузерный логин, либо токен.
• ⏸ Pending approval — сервер из общего конфига проекта, его надо один раз подтвердить внутри сессии.

Если нужен токен — передай его прямо при добавлении:

claude mcp add --transport http github https://api.githubcopilot.com/mcp \
  --header "Authorization: Bearer ТВОЙ_ТОКЕН"

А локальному серверу ключ обычно нужен переменной окружения — флаг --env:

claude mcp add weather --env API_KEY=твой_ключ -- npx -y weather-mcp

Обрати внимание на порядок: --env идёт до разделителя --. Всё, что после разделителя, считается командой запуска сервера, и флаг туда просто уедет.

Какие именно переменные нужны — всегда написано в документации сервера. Про сами ключи и почему их не стоит вставлять в код — есть отдельный разбор.

4. Попробуй в деле

Запусти сессию и попроси что-то, что без сервера невозможно:

claude

Через сервер playwright открой example.com и скажи, какой там заголовок.

Называть сервер по имени в обычной работе не нужно — агент сам выбирает инструменты. Здесь это нужно только чтобы убедиться: ответ пришёл через сервер, а не из головы модели.

Внутри сессии есть команда /mcp — покажет список серверов, их статус и позволит переподключиться, не выходя из разговора.

5. Реши, где сервер должен жить

Область видимости задаётся при добавлении и потом не меняется — только удалить и добавить заново. Вариантов три:

• local (по умолчанию) — только ты, только этот проект. Запись уходит в ~/.claude.json.
• --scope user — только ты, но во всех проектах. Для универсальных штук вроде браузера.
• --scope project — файл .mcp.json в корне проекта. Его коммитят в репозиторий, и у коллег сервер подхватится сам.

claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp

Не помнишь, куда положил — спроси: claude mcp get имя покажет и область, и полный адрес.

Что получится

После ✔ Connected у агента появляются новые инструменты, и он берёт их сам, когда задача того требует. Ты больше не копируешь данные из соседней вкладки в чат — агент ходит в систему напрямую.

И сразу важное про гигиену. Каждый подключённый сервер постоянно занимает место в контекстном окне: имена его инструментов и описания загружаются в каждую сессию. Пять серверов «на всякий случай» — это заметный кусок контекста впустую и лишние деньги.

Поэтому правило простое: подключил, попробовал, не пользуешься — снеси.

claude mcp remove playwright

Сервер добавился, а инструментов нет — что делать?

Скорее всего, ему не хватает переменной окружения — чаще всего ключа. Открой /mcp в сессии и посмотри список инструментов сервера: если он пустой, читай документацию и добавь недостающее через --env.

Можно ли просто написать .mcp.json руками?

Можно, формат открытый. Но учти две вещи: файл читается при старте сессии — после правки её надо перезапустить, и путь имеет значение (.mcp.json в корне проекта, а не где-то в папке настроек). Команда claude mcp add просто не даёт ошибиться ни в том, ни в другом.

MCP работает только в Claude Code?

Нет, MCP — открытый стандарт, серверы одинаковые для разных клиентов. Меняется только способ подключения: где-то команда, где-то настройки приложения. Сам сервер переписывать не нужно.