Как подключить MCP к Claude Code: команды, области и примеры

Автор: Мария Бородкина · Дата: 20.09.2026 · Проверено: 20.09.2026 · Время чтения: 8 минут

Как подключить MCP к Claude Code — одной командой в терминале: claude mcp add --transport http <имя> <url> для облачного сервера или claude mcp add <имя> -- <команда запуска> для локального. После этого Claude Code видит инструменты сервера и вызывает их сам: читает макет из Figma, открывает страницу в браузере через Playwright, достаёт актуальную документацию библиотеки через Context7. Ниже — порядок действий по официальной документации, три области подключения и типичные ошибки.

Мой контекст: у меня к Claude Code подключены Figma, Notion, Google Drive, Gmail и несколько собственных серверов, через которые агенты читают Telegram и общую память. Половина проблем при подключении у меня и у знакомых была одна и та же — забытый -- перед командой запуска и сервер, добавленный не в ту область. Оба случая разобраны ниже.

Кратко

• MCP (Model Context Protocol, протокол контекста модели) — открытый стандарт, по которому Claude Code подключается к внешним инструментам: базам, трекерам задач, дизайн-редакторам, браузеру.
• Подключение — команда claude mcp add. Облачный сервер: --transport http и адрес. Локальный: команда запуска после --.
• Проверка — claude mcp list (статус ✔ Connected) и /mcp внутри сессии.
• Область по умолчанию — local: сервер виден только в текущем проекте и только вам. Для команды — --scope project (файл .mcp.json в репозитории), для всех своих проектов — --scope user.

Что такое MCP и зачем он Claude Code

Без MCP Claude Code работает только с тем, что лежит в проекте и что вы вставили в чат. С MCP-сервером он получает инструменты (tools) и ресурсы (resources) чужой системы: может «прочитать задачу ENG-4521 в трекере и сделать PR», «проверить ошибки в мониторинге», «обновить письмо по новому макету из Figma». Документация Anthropic формулирует критерий просто: подключайте сервер, когда ловите себя на том, что копируете данные из другого инструмента в чат.

Сервер может быть трёх видов по способу связи (transport):

Транспорт	Где работает	Когда выбирать	Команда
HTTP	облачный сервис (Notion, Figma, Context7)	по умолчанию для удалённых серверов; поддерживает OAuth	claude mcp add --transport http <имя> <url>
stdio	локальный процесс на вашей машине	инструменты с доступом к файлам и системе (Playwright, свои скрипты)	claude mcp add <имя> -- <команда>
SSE	устаревший вариант удалённого сервера	только если сервис не даёт HTTP-адреса; Claude Code с версии 2.1.265 сам переключается на SSE	claude mcp add --transport sse <имя> <url>

Есть и четвёртый вариант — WebSocket для серверов, которые сами присылают события в сессию; он настраивается только через JSON (claude mcp add-json), флаг --transport ws не принимает.

Шаг 1. Подключить облачный сервер (HTTP)

Самый частый случай. Синтаксис и живой пример из документации:

# Синтаксис
claude mcp add --transport http <имя> <url>

# Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Сервер с ключом в заголовке
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Если сервер требует входа через OAuth, после добавления откройте сессию claude, наберите /mcp и выберите сервер — Claude Code откроет страницу авторизации в браузере. Статус ! Needs authentication в claude mcp list означает именно это, а не ошибку.

Шаг 2. Подключить локальный сервер (stdio)

Локальный сервер — это процесс, который Claude Code запускает сам. Ключевая деталь — двойной дефис --: всё, что после него, уходит серверу без изменений, всё до него — опции самого Claude Code.

# Синтаксис
claude mcp add [опции] <имя> -- <команда> [аргументы]

# Пример из документации: сервер Airtable
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Без -- Claude Code попытается прочитать флаги сервера (например --port 8080) как свои и завершится ошибкой. Вторая ловушка — порядок: если имя сервера стоит сразу после --env, CLI примет его за ещё одну пару KEY=value; ставьте между ними любую другую опцию, например --transport stdio.

Переменные окружения передаются через --env KEY=value (можно несколько). В окружение сервера Claude Code добавляет CLAUDE_PROJECT_DIR — корень проекта, чтобы сервер не зависел от текущей папки.

Шаг 3. Выбрать область: local, project или user

Область (scope) определяет, в каких проектах сервер загружается и видит ли его команда.

Область	Где загружается	Видна команде	Где хранится
local (по умолчанию)	только текущий проект	нет	~/.claude.json, в записи этого проекта
project	только текущий проект	да, через git	.mcp.json в корне проекта
user	все ваши проекты	нет	~/.claude.json

# local — по умолчанию
claude mcp add --transport http stripe https://mcp.stripe.com

# project — в .mcp.json, коммитится в репозиторий
claude mcp add --transport http github --scope project https://api.githubcopilot.com/mcp/

# user — для всех проектов на этой машине
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Три правила из документации, которые экономят часы:

1. Если один сервер описан в нескольких местах, побеждает local, затем project, затем user; запись берётся целиком, поля не сливаются.
2. Сервер из .mcp.json при первом запуске требует подтверждения: статус ⏸ Pending approval — запустите claude в этом проекте и одобрите.
3. Ключи не кладите в .mcp.json: он попадает в git. Для командных настроек используйте ${VAR} — Claude Code подставит переменную окружения при запуске.

Шаг 4. Проверить и управлять

claude mcp list          # все серверы и статус: ✔ Connected / ! Needs authentication / ✘ Failed to connect
claude mcp get notion    # детали одного сервера
claude mcp remove notion # удалить (для удалённых серверов сотрутся и OAuth-токены)

Внутри сессии — команда /mcp: статус, авторизация, включение и выключение серверов для проекта. Строка Added … после claude mcp add означает только, что конфигурация записана; подключился ли сервер, показывает claude mcp list.

Ещё два способа использовать сервер помимо инструментов: ресурсы через @ (например @github:issue://123 прямо в запросе) и промпты сервера как команды — /mcp__github__list_prs.

Примеры: Figma, Playwright, Context7

Figma. У Figma два MCP-сервера: удалённый на https://mcp.figma.com/mcp (рекомендуемый, работает на всех тарифах) и локальный через десктопное приложение (для корпоративных сценариев). Подключение удалённого:

claude mcp add --transport http figma https://mcp.figma.com/mcp

Затем /mcp → figma → вход через браузер. После этого достаточно вставить ссылку на фрейм: Claude Code читает структуру макета, переменные и скриншот, а при полном доступе к файлу — создаёт и правит слои.

Playwright. Локальный сервер от Microsoft, который управляет реальным браузером: открыть страницу, кликнуть, заполнить форму, снять скриншот. Команда из README проекта:

claude mcp add playwright npx @playwright/mcp@latest

Нужен установленный Node.js. Я использую его для проверки лендингов после правок: «открой страницу, пройди форму, покажи скриншот».

Context7. Отдаёт актуальную документацию библиотек прямо в контекст, чтобы модель не писала код по устаревшим версиям. Удалённый сервер https://mcp.context7.com/mcp; ключ выдаётся бесплатно в личном кабинете и повышает лимит запросов:

claude mcp add --transport http context7 https://mcp.context7.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Проект также предлагает автоустановку npx ctx7 setup --claude.

Если инструкция написана для другого клиента

Большинство серверов описывают установку для Claude Desktop или Cursor и дают блок JSON вместо команды. Документация Claude Code переводит его так: берите объект внутри mcpServers (без обёртки) и передавайте в claude mcp add-json:

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

Две правки, без которых запись не заработает: у удалённого сервера с url обязательно поле "type": "http" (без него Claude Code считает запись локальным сервером и пропускает её), а в имени — только буквы, цифры, дефис и подчёркивание. Серверы, уже настроенные в Claude Desktop, импортируются одной командой: claude mcp add-from-claude-desktop.

Типичные ошибки

• ✘ Failed to connect у локального сервера — чаще всего не установлен Node.js или пакет, либо забыт --. Запустите команду сервера вручную в терминале и посмотрите вывод.
• Сервер добавлен, но в другом проекте его нет — он в области local. Переподключите с --scope user.
• MCP server "…" has a "url" but no "type" — добавьте "type": "http" в JSON.
• Слишком много серверов «съедают» контекст — с текущими версиями это не так: Claude Code загружает при старте только названия инструментов и описания серверов, а полные определения подтягивает по мере надобности (tool search).
• Сервер читает внешний контент (страницы, письма, задачи) — это канал для инъекций в промпт. Документация прямо просит подключать только те серверы, которым доверяете.

Что дальше

Подключите один сервер, который закроет самое частое копирование в чат — для большинства это трекер задач или документация. Затем вынесите командные серверы в .mcp.json, а личные с ключами держите в local или user. Следующий шаг после MCP — навыки (skills) и субагенты, которые используют эти инструменты по сценарию; об этом — в разделе «Скиллы».

Актуально на 20 сентября 2026 года. Команды и статусы сверены с официальной документацией Claude Code; версии Claude Code, где поведение менялось, указаны в тексте.

Источники

1. Claude Code Docs — Connect Claude Code to tools via MCP: https://code.claude.com/docs/en/mcp
2. Figma Help Center — Guide to the Figma MCP server: https://help.figma.com/hc/en-us/articles/32132100833559-Guide-to-the-Figma-MCP-server
3. Playwright MCP, README (Microsoft): https://github.com/microsoft/playwright-mcp
4. Context7, README (Upstash): https://github.com/upstash/context7