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

MCP-сервер подключается в Claude Code одной командой: claude mcp add с именем сервера и адресом или командой запуска. Допустим, вы хотите, чтобы агент сам открыл страницу сайта и прочитал её заголовок. Сам по себе он этого не умеет, для этого и нужен MCP-сервер. После добавления вы проверяете статус через claude mcp list и, если сервер просит вход, проходите авторизацию в /mcp. Ниже шпаргалка по командам, таблица областей (scope) и три примера: Playwright, Figma и файловая система.

Работает ли Claude Code в России?

Claude и Claude Code официально в России не работают, российские карты для оплаты не принимаются. Если вы читаете из России, начните с оплаты: способы подробно разобраны в отдельной статье. Дальше мы считаем, что Claude Code у вас уже установлен. Если нет, начните с руководства для новичка.

Какие команды вам понадобятся?

Все команды вы выполняете в обычном терминале, не внутри сессии Claude Code. Исключение: /mcp, она работает только в сессии.

Задача	Команда
Удалённый сервер по HTTP (рекомендуется)	claude mcp add --transport http <имя> <адрес>
Удалённый сервер по SSE (устарел)	claude mcp add --transport sse <имя> <адрес>
Локальный сервер (stdio)	claude mcp add <имя> -- <команда> [аргументы]
Добавить из готового JSON	claude mcp add-json <имя> '<json>'
Импорт из Claude Desktop	claude mcp add-from-claude-desktop
Список серверов со статусом	claude mcp list
Подробности по одному серверу	claude mcp get <имя>
Удалить сервер	claude mcp remove <имя>
Сбросить ответы на вопрос «доверять серверу из .mcp.json?»	claude mcp reset-project-choices
Войти по OAuth из терминала	claude mcp login <имя>
Панель серверов внутри сессии	/mcp

Для истории с браузером хватит добавления сервера и списка. Остальные строки пригодятся, когда серверов станет больше.

Какой транспорт выбрать?

Сначала решите, откуда запускается сервер: по чужому адресу или у вас на компьютере. От этого зависит транспорт.

• http для удалённых серверов. Документация называет его рекомендуемым, он поддерживает OAuth.
• sse помечен в документации как устаревший (deprecated). Берите его, только если у сервера нет HTTP-адреса.
• stdio для программ, которые запускаются на вашем компьютере.

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

В каком порядке писать флаги?

Флаги встречаются почти в каждой инструкции к серверу, поэтому сверьтесь с таблицей.

Флаг	Что делает
--transport, -t	Тип подключения: http, sse или stdio
--scope, -s	Область: local (по умолчанию), project или user
--env, -e	Переменная окружения для сервера: -e KEY=value
--header, -H	HTTP-заголовок, например "Authorization: Bearer ..."

Порядок здесь важен: все флаги Claude Code ставьте до имени сервера, а двойной дефис -- перед командой запуска. Всё после него уходит серверу без изменений. Без -- Claude Code примет флаги сервера, например --port, за свои.

claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080

Есть и вторая тонкость: после --env не ставьте имя сервера сразу. Между ними нужен другой флаг, например --transport stdio, иначе имя прочитается как ещё одна пара KEY=value.

Как забрать серверы из других мест?

Если серверы уже настроены в Claude Desktop, их можно забрать командой claude mcp add-from-claude-desktop. По документации она работает только на macOS и в WSL, а имена переносятся, если состоят из букв, цифр, дефисов и подчёркиваний.

Бывает, что в инструкции сервера есть только блок JSON для другого клиента. Тогда передайте в add-json объект внутри mcpServers, без внешней обёртки:

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

Для HTTP-сервера в JSON обязательно поле "type": "http". Запись с url, но без type Claude Code читает как stdio, пропускает и пишет об ошибке.

Кто увидит добавленный вами сервер?

Вы добавили сервер, и сразу возникает вопрос: увидят ли его коллеги и появится ли он в других проектах. Это решает область (scope).

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

Если сервер с одним именем описан в нескольких областях, используется одно описание, поля не объединяются. Приоритет такой: local, затем project, затем user.

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

claude mcp add --transport http shared-server --scope project https://example.com/mcp

Claude Code создаст или обновит .mcp.json. В этом файле можно ссылаться на переменные окружения: ${VAR} или ${VAR:-значение}. Так секреты остаются вне репозитория:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

Первый раз сервер из .mcp.json запрашивает подтверждение в интерактивной сессии. Это защита, потому что клонированный репозиторий не может подключить сервер сам.

Пример 1. Как дать агенту браузер?

Вернёмся к вашей задаче с заголовком страницы. Playwright MCP от Microsoft даёт Claude Code управление браузером: открыть страницу, прочитать её структуру, нажать кнопку. Требуется Node.js 18 или новее. Команду для Claude Code мы взяли из README проекта:

claude mcp add playwright npx @playwright/mcp@latest

1. Выполните команду в терминале.
2. Проверьте: claude mcp list. Рядом с playwright должно стоять ✔ Connected.
3. Запустите claude и попросите: «Открой страницу example.com и скажи, какой на ней заголовок».

Браузер по умолчанию открывается с видимым окном. Режим без окна включается флагом --headless, а профиль в памяти без записи на диск флагом --isolated. Их добавляют в конец команды запуска: claude mcp add playwright -- npx @playwright/mcp@latest --headless. В README также сказано, что флаги --allowed-origins и --blocked-origins для ограничения адресов защитой не служат: это удобство, а не граница безопасности.

Если агент пишет код, авторы README отдельно предлагают вариант Playwright CLI со скиллами, и он экономнее по токенам. Про скиллы читайте в статье о скиллах Claude Code.

Пример 2. Как перенести макет в код?

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

Самый простой путь для Claude Code по справке Figma идёт через плагин:

claude plugin install figma@claude-plugins-official

Плагин включает настройки сервера и скиллы Figma. После установки перезапустите Claude Code, откройте /plugin, на вкладке Installed выберите figma и пройдите вход в браузере (Allow access).

Если плагины у вас заблокированы, добавьте сервер вручную:

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

Чтобы сервер работал во всех проектах, добавьте --scope user. Затем начните новую сессию, введите /mcp, выберите figma, нажмите Authenticate и разрешите доступ в браузере. Должно появиться сообщение «Authentication successful. Connected to figma».

Прежде чем ставить, сверьтесь с тарифом: от него зависит, получится ли у вас запись в файлы. Вот условия по справке Figma.

• Удалённый сервер доступен на планах Starter, Professional, Education, Organization, Government и Enterprise.
• Для записи в файлы вне ваших черновиков нужно полное место (Full seat). Запись на холст сейчас в бета-версии и бесплатна, позже её переведут на оплату по использованию.
• Десктопный сервер требует приложение Figma и место Dev или Full на платных планах Professional и выше. Он запускается в Dev Mode, работает по адресу http://127.0.0.1:3845/mcp, подключается командой claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp.

Пример 3. Что попробовать без ключей?

Если браузер и Figma вам пока не нужны, потренируйтесь на файлах: здесь нет ни регистрации, ни ключей. Официальный сервер @modelcontextprotocol/server-filesystem из репозитория modelcontextprotocol/servers читает и пишет файлы, ищет их и показывает метаданные, но только в папках, которые вы ему назвали. В README он запускается через npx -y @modelcontextprotocol/server-filesystem и путь к папке. Для Claude Code мы собрали команду по правилам stdio из документации Anthropic:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/Documents

Укажите одну рабочую папку, а не весь домашний каталог. Можно перечислить несколько путей через пробел. Другие популярные серверы собраны в подборке. Если вам нужен доступ только к текущему проекту, отдельный сервер, скорее всего, не нужен, потому что сам Claude Code уже читает и правит файлы проекта.

Как передать серверу токен или войти?

Часто сервер добавлен, но без ключа или входа он молчит. Есть три способа.

• Токен в заголовке: claude mcp add --transport http secure-api https://api.example.com/mcp --header "Authorization: Bearer your-token".
• Переменная для локального сервера: claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server.
• OAuth: если сервер отвечает ошибкой 401 или 403, он помечается в /mcp. Откройте /mcp, выберите сервер и пройдите вход в браузере. То же из терминала делает claude mcp login <имя>. Выйти или стереть доступ: claude mcp logout <имя> либо пункт «Clear authentication» в /mcp.

Если в заголовке указан токен и сервер его отклоняет, Claude Code сообщит об обрыве подключения и на OAuth не переключится. Проверьте токен или уберите заголовок.

Что делать, если сервер не подключился?

Вы добавили сервер, а в списке у него нет статуса Connected. Идите по пунктам сверху вниз.

1. claude mcp list. Рядом с каждым сервером стоит статус: ✔ Connected, ! Needs authentication, ✘ Failed to connect. У упавшего сервера в той же строке будет причина, например код ответа.
2. claude mcp get <имя>. Показывает подробности, причина ошибки стоит в строке Issue:.
3. /mcp в сессии. Панель показывает статус, число инструментов и позволяет переподключить или пройти вход. Команда /mcp reconnect all повторяет попытку для всех упавших серверов (в интерактивном терминале нужна версия 2.1.284 или новее).
4. Статус Pending approval. Сервер из .mcp.json ждёт вашего подтверждения: запустите claude интерактивно и подтвердите.
5. Время запуска. Таймаут старта задаёт переменная MCP_TIMEOUT в миллисекундах: MCP_TIMEOUT=10000 claude даёт 10 секунд.
6. Большой ответ. Claude Code предупреждает, если ответ инструмента больше 10 000 токенов, и по умолчанию обрезает его на 25 000. Лимит поднимается так: MAX_MCP_OUTPUT_TOKENS=50000 claude.
7. Пробел или перенос строки в токене. Claude Code предупреждает о лишних пробелах в значениях в claude mcp list и /mcp, но сам их не убирает.
8. Неустановленная переменная. Если в .mcp.json есть ${VAR}, а переменной нет, будет предупреждение, а в значение попадёт сам текст ${VAR}.

Имя сервера в командах claude mcp может состоять только из букв, цифр, дефисов и подчёркиваний. Лимиты самой подписки это не затрагивает, о них читайте в статье про лимиты Claude Code.

Что проверить до подключения?

Документация Anthropic прямо предупреждает: подключайте только серверы, которым доверяете. Серверы, которые тянут внешний контент, открывают путь для prompt injection, то есть вредоносный текст на странице или в тикете может попытаться изменить указания агента. Anthropic проверяет коннекторы перед добавлением в свой каталог, но аудит безопасности серверов не проводит.

Перед командой claude mcp add пройдите по короткому чек-листу.

• Кто автор. Официальный репозиторий компании или проект без истории? У серверов из случайных статей автор неизвестен.
• Что запускается. Команда stdio запускает программу на вашем компьютере с вашими правами. Прочитайте, что она делает, особенно если после -- стоит незнакомый пакет.
• Какие права у ключа. Выдавайте токен только на чтение, как в примере документации с базой данных и пользователем readonly.
• Куда смотрит папка. Файловому серверу называйте одну рабочую папку.
• Что лежит в репозитории. Файл .mcp.json из чужого проекта может подключить что угодно. Документация отмечает, что просмотр этого файла не показывает все серверы сессии: часть задана в других областях и плагинами.
• Что видят остальные. Секреты кладите в переменные окружения, а не в .mcp.json, который уходит в git.

Полный разбор рисков есть в разделе безопасности статьи о MCP для новичка.

Что вы ещё можете спросить?

Как добавить MCP одной командой?

Для удалённого сервера: claude mcp add --transport http имя адрес. Для локального: claude mcp add имя -- команда. После добавления выполните claude mcp list.

Где Claude Code хранит настройки MCP?

Серверы областей local и user лежат в ~/.claude.json. Серверы области project лежат в файле .mcp.json в корне проекта.

Чем отличаются stdio, http и sse?

stdio запускает программу у вас на компьютере. http подключается к удалённому серверу и рекомендуется для облачных сервисов. sse тоже удалённый, но документация называет его устаревшим.

Нужно ли перезапускать Claude Code?

Для Figma справка рекомендует начать новую сессию после добавления. Если сервер не виден в /mcp, перезапустите Claude Code.

Как удалить сервер?

Выполните claude mcp remove имя. Для удалённого сервера Claude Code заодно стирает сохранённые токены OAuth. Если одно имя есть в двух областях, укажите область: --scope.

Можно перенести серверы из Claude Desktop?

Да, командой claude mcp add-from-claude-desktop, но только на macOS и в WSL.

Сервер подключён, а Claude им не пользуется?

Проверьте в /mcp, что у сервера есть инструменты: панель отмечает серверы, которые заявляют инструменты, но не отдают их. Ещё попросите Claude прямо назвать сервер в задаче.

Увидит ли сервер ваши файлы?

Только к тому, что сервер умеет и что вы ему разрешили. Поэтому права токена и список папок ограничивайте заранее.

Чем всё закончится и что сверить?

Если вы шли по первому примеру, claude mcp list показывает рядом с playwright статус ✔ Connected, а Claude открывает страницу и называет её заголовок.

Осталось сверить даты. Данные взяты из документации Anthropic и страниц самих серверов, по данным официальных сайтов на октябрь 2026. Запись на холст в Figma сейчас в бета-версии, позже её переведут на оплату по использованию. Лимиты запросов и условия доступа смотрите на странице «Plans, access, and permissions» в справке Figma, потому что цифры меняются.