Как подключить MCP-серверы к Claude Code

Подключить MCP-сервер к Claude Code — значит буквально дать агенту новую способность: читать актуальную документацию, открывать браузер, ходить в живую базу данных. Всё это без платных API, тремя-четырьмя строчками конфига. В этой статье разберём три готовых сервера — Context7, Playwright и Postgres — и пройдём путь от установки до первого рабочего вызова.

Если вы ещё не читали, что такое MCP и как Claude видит серверы — начните с той статьи. Здесь идём сразу к практике.

Что такое .mcp.json и зачем он нужен

Claude Code поддерживает два способа добавить MCP-сервер: командой в терминале (claude mcp add) и напрямую через файл конфигурации. Оба дают одинаковый результат — записывают сервер в .mcp.json.

Ключевое понятие здесь — scope, область видимости конфига:

• project — файл .mcp.json лежит в корне репозитория, коммитится в git, доступен всем в команде. Используйте для серверов, которые нужны всему проекту: доки стека, браузерные тесты, dev-база.
• local — конфиг хранится вне репозитория, не коммитится. Подходит для личных токенов и продовых секретов — тех, что нельзя шарить.

Базовая структура .mcp.json выглядит так:

{
  "mcpServers": {
    "имя-сервера": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "пакет-сервера"]
    }
  }
}

type: stdio означает, что Claude запускает сервер локально как дочерний процесс и общается с ним через стандартный поток ввода-вывода. Никакого сетевого подключения наружу — сервер живёт на вашей машине.

Сервер 1: Context7 — актуальные доки вместо памяти модели

Первая боль fullstack-разработчика: агент отвечает по памяти, а там устаревший синтаксис NestJS, React или Prisma. Context7 решает это радикально — тянет актуальную документацию прямо во время вызова.

Подключение командой:

claude mcp add --scope project --transport stdio context7 -- npx -y @upstash/context7-mcp

Или вручную в .mcp.json:

{
  "mcpServers": {
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

npx -y означает: Claude сам загрузит пакет при первом запуске, ставить ничего заранее не нужно.

Проверка: выполните в терминале:

claude mcp list

В списке должен появиться context7 со статусом connected. Внутри сессии наберите /mcp — увидите инструменты сервера (resolve-library-id, query-docs или аналогичные; точные имена сверьтесь с актуальной документацией).

Реальный пример. На проекте CoffeeCRM (Next.js + NestJS) спрашиваем агента: «Свериться по Context7: как в актуальной версии NestJS объявить DTO с валидацией для создания заказа?» — агент сам вызывает Context7, тянет свежую доку и отвечает по ней, а не по обучающим данным прошлого года. Это и есть защита от API-галлюцинаций.

Сервер 2: Playwright — глаза агента в браузере

Playwright-сервер даёт агенту набор инструментов браузерной автоматизации: открыть URL, кликнуть, заполнить форму, сделать снимок DOM. Запускается локально, headless или с видимым окном.

Подключение:

claude mcp add --scope project --transport stdio playwright -- npx -y @playwright/mcp@latest

В .mcp.json:

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

При первом запуске Playwright может докачать браузеры — это нормально, просто подождите.

После подключения в /mcp у сервера playwright появится большой набор инструментов: browser_navigate, browser_click, browser_snapshot и другие (точный список зависит от версии пакета).

Реальный пример. Фронт CoffeeCRM поднят на localhost:3001. Промпт: «Открой страницу списка заказов на http://localhost:3001/orders, сделай снимок и скажи, есть ли кнопка “Новый заказ” и таблица заказов.» Агент открывает браузер, видит реальный рендер, возвращает наблюдаемый результат — не догадку по коду, а то, что отобразилось на экране. Именно на этом строятся автоматические UI-проверки, о которых мы говорим в статье code review и тесты с агентом.

Сервер 3: Postgres — чтение живой базы без ручного копипаста

Третья боль: нужно показать агенту схему таблиц или реальные данные, и каждый раз приходится запускать psql, копировать результат, вставлять в чат. Postgres MCP-сервер убирает этот шаг полностью — агент сам ходит в базу.

Принципиально важный момент: подключаем базу только на чтение, через отдельную read-only роль. Сначала создаём её в Postgres:

CREATE ROLE readonly LOGIN PASSWORD 'readonly';
GRANT CONNECT ON DATABASE coffeecrm TO readonly;
GRANT USAGE ON SCHEMA public TO readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO readonly;

Подключение через @bytebase/dbhub (сервер, рекомендованный официальной документацией Claude Code как пример БД-сервера на дату написания; сверьтесь с актуальной документацией):

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

В .mcp.json:

{
  "mcpServers": {
    "coffeecrm-db": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y", "@bytebase/dbhub",
        "--dsn", "postgresql://readonly:readonly@localhost:5432/coffeecrm"
      ]
    }
  }
}

Реальный пример. Промпт 1: «Покажи схему таблицы orders — какие колонки и типы.» Промпт 2: «Сколько заказов в статусе active и какие позиции в последнем заказе?» Агент сам формирует SELECT, читает живую базу и возвращает данные. Это пример работы с готовыми MCP-серверами в реальном проекте.

Итоговый .mcp.json для CoffeeCRM

Собираем все три сервера в один файл:

{
  "mcpServers": {
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "coffeecrm-db": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y", "@bytebase/dbhub",
        "--dsn", "postgresql://readonly:readonly@localhost:5432/coffeecrm"
      ]
    }
  }
}

Этот файл коммитится в репозиторий — любой разработчик, клонировавший проект, сразу получит все три сервера.

Безопасность: что коммитить, а что нет

Несколько правил, которые снимают большинство вопросов:

• В .mcp.json (project scope) коммитятся только безопасные данные: имена npm-пакетов, локальные dev-DSN с тестовыми паролями, публичные сервисы без токенов.
• Продовые DSN, токены, API-ключи — не в репозиторий. Подключайте через scope local или используйте переменные окружения (${DATABASE_URL}) с хранением значений вне репо.
• Read-only роль для БД — обязательный стандарт. Агент исследует данные, он не должен их изменять. Права на запись — только через инструменты с явным контролем.
• После любых изменений в .mcp.json — перезапустите сессию Claude Code, чтобы новые серверы подхватились.

Если сервер не появляется в claude mcp list или показывает ошибку: проверьте имя npm-пакета в актуальной документации, убедитесь, что node и npx доступны в PATH, и перезапустите сессию.

Итог

Подключить MCP-сервер к Claude Code — задача на пять минут. Три строчки в .mcp.json — и агент получает новую способность: читать свежую документацию через Context7, видеть реальный браузерный рендер через Playwright, ходить в живую базу через Postgres.

Принципиально важно: агент сам решает, какой инструмент вызвать — это model-controlled поведение. Вы лишь добавляете способности, а не прописываете сценарии вызова.

Если стандартных серверов не хватает и нужны инструменты с логикой вашего проекта — следующий шаг это написать свой MCP-сервер. Как это делается системно — с архитектурой, безопасностью и интеграцией в реальный стек — разбираем в полном курсе по Claude Code.