Как подключить MCP к Claude Code?

Одной командой в терминале: claude mcp add, имя сервера и его адрес с флагом --transport http, а для локального сервера - двойное тире и команда запуска. Выполнять её нужно до запуска сессии агента. После добавления проверь статус командой claude mcp list: рабочее состояние называется Connected.

Что такое MCP-сервер простыми словами?

Это программа или облачный сервис, который по протоколу MCP отдаёт агенту свои инструменты, данные и заготовки запросов. Сервер может работать у тебя на компьютере или в облаке у сервиса. Claude Code подключает его как ещё один набор инструментов и сам решает, когда им воспользоваться по ходу задачи.

Как перенести MCP-серверы из Claude Desktop в Claude Code?

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

Какие MCP-серверы поставить в Claude Code первыми?

Первым - сервер документации Claude Code: он не требует входа и проверяет сам механизм. Дальше - сервисы, из которых ты сейчас копируешь данные в чат: браузер через Playwright, Notion, GitHub. Команды для них взяты из официальных инструкций авторов серверов. Старые подборки советуют серверы, которые команда MCP уже перенесла в архив.

Почему MCP-сервер не появляется в /mcp?

Чаще всего сервер добавлен в другой папке: область local по умолчанию привязана к проекту, где выполнили команду. Вторая частая причина - конфиг лежит не там: свои серверы Claude Code берёт из ~/.claude.json и .mcp.json в корне проекта, а пути вроде ~/.claude/mcp.json не читает. После правки .mcp.json сессию нужно перезапустить.

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

Что такое MCP в Claude Code?

Коротко: MCP в Claude Code - это способ подключить агенту внешний сервис: Notion, GitHub, браузер, базу данных. Сервис отдаёт агенту инструменты через MCP-сервер, подключение - одна команда claude mcp add. Дальше агент сам берёт данные из сервиса, копировать их в чат не нужно.

MCP в Claude Code нужен, чтобы агент работал с твоими сервисами напрямую: читал задачи из трекера, страницы из Notion, открывал сайт в браузере. Признак из документации Anthropic простой: ты копируешь в чат данные из другой программы.

Команды ниже сверены по документации Anthropic и справке программы версии 2.1.278 на macOS, серверы взяты из официальных инструкций их авторов.

Авторы протокола сравнивают MCP с разъёмом USB-C: один стандарт вместо своего провода под каждое устройство. Сервер отдаёт агенту инструменты (найти задачу, открыть страницу), ресурсы (файлы и записи для чтения) и промпты (заготовки запросов). Работает он у тебя на компьютере или в облаке у сервиса, определение - в словаре: что такое MCP.

Кстати, сама ClaudeBase подключается к агенту тем же способом, как MCP-сервер: агент сам ищет в ней правила, скиллы и настройки и забирает нужное в работу. На странице доступа к ClaudeBase видно, что входит в базу.

Где вы сейчас

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

Слышишь про MCP впервые. Шаги 1 и 2.
На руках команда из инструкции сервиса. Раздел про транспорты: из каких частей она состоит.
Сервер добавлен, но не работает. Статусы в шаге 2, потом частые ошибки.
Сервер нужен всей команде. Области видимости, файл .mcp.json и раздел о рисках.

Шаг 1. Как подключить первый сервер одной командой?

Коротко: Сервер добавляется командой claude mcp add в обычном терминале, до запуска сессии агента. Для первой пробы подходит сервер документации Claude Code: он работает в облаке Anthropic, вход и настройка не нужны. Команда сохраняет запись и печатает подтверждение.

Нужны Claude Code с выполненным входом и терминал в папке проекта, подойдёт даже пустая. Агента ещё нет - начни со статьи как установить Claude Code, терминал в новинку - с Claude Code в терминале.

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

claude mcp add - регистрирует сервер.
--transport http - сервер работает по адресу в интернете.
claude-code-docs - имя, его придумываешь ты, под ним сервер подписан в ответах агента.
https://code.claude.com/docs/mcp - адрес сервера.

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

Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to local config

local config - сервер сохранён для тебя и только в этом проекте.

Команда начинается со слова claude: так программа зовётся в терминале, хоть клод код, хоть клауд код её назови в поиске.

Шаг 2. Как проверить, что сервер подключился?

Коротко: Строка Added значит одно: запись сохранена. Отвечает ли сервер, она не говорит. Статус проверяют командой claude mcp list в терминале или панелью /mcp в сессии. Рабочее состояние называется Connected, остальные статусы подсказывают, что чинить.

claude mcp list
claude mcp get claude-code-docs

Статус	Что значит	Что делать
`✔ Connected`	сервер готов	пользоваться
`! Needs authentication`	ждёт входа	войти через `/mcp` или `claude mcp login`
`! Connected · tools fetch failed`	не отдал список инструментов	подробности в `claude mcp get`
`✘ Failed to connect`	сервер не ответил	строка `Issue:` в `claude mcp get`
`✘ Connection error`	попытка подключения упала	проверить адрес или запустить команду сервера руками
`⏸ Pending approval`	сервер из `.mcp.json` не подтверждён	запустить `claude` и подтвердить

На старой консоли Windows 10 вместо галочки и крестика стоят √ и ×. Теперь запусти claude и попроси:

Найди через сервер claude-code-docs, что делает переменная MCP_TIMEOUT

Обычно имя сервера называть не нужно, здесь оно для проверки. При первом вызове агент может спросить разрешение, подтверждай. Вызов инструмента в ответе подписан именем сервера, так видно, что ответ пришёл через MCP.

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

Коротко: Транспорт - способ, которым Claude Code обменивается сообщениями с сервером. Серверу в интернете нужен http, программе, которую Claude Code сам запускает у тебя на компьютере, - stdio. SSE устарел, WebSocket задаётся только через JSON, а по команде из инструкции транспорт обычно виден сразу.

Транспорт	Где сервер	Как добавить
`http`	в облаке, его советует документация	`--transport http <имя> <адрес>`
`stdio`	программа на твоём компьютере, по умолчанию	`<имя> -- <команда запуска>`
`sse`	в облаке, устарел	`--transport sse <имя> <адрес>`
`ws`	в облаке, постоянное соединение	только `claude mcp add-json` или `.mcp.json`

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

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

Всё после двойного тире - команда запуска сервера, она передаётся как есть. Без -- программа примет флаги сервера вроде -y за свои. Ключ передаётся флагом -e до двойного тире, и сразу за --env имя сервера не ставят: его примут за ещё одну пару «ключ=значение». С версии 2.1.265 команда с --transport http сама переходит на SSE, если сервер не принимает HTTP.

Где сохранится сервер: local, project или user?

Коротко: Областей хранения три. По умолчанию стоит local: сервер доступен тебе и только в папке, где ты его добавил. С user сервер доступен тебе во всех проектах, с project - всем участникам проекта через файл .mcp.json. Задаётся это флагом --scope, а сменить - только удалением и повторным добавлением.

Область	Где запись	Кому доступен
`local`	`~/.claude.json`, в записи проекта	тебе, в этом проекте
`project`	`.mcp.json` в корне проекта	всем, кто скачает проект
`user`	`~/.claude.json`, ключ `mcpServers` верхнего уровня	тебе, во всех проектах

На Windows файл ~/.claude.json лежит по пути %USERPROFILE%\.claude.json. Слово local тут не связано с файлом settings.local.json, об остальных настройках - в статье Claude Code - настройка с нуля.

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

Если сервер с одним именем записан в нескольких местах, побеждает старший источник: local, затем project, затем user, дальше плагины и коннекторы claude.ai. Свои серверы Claude Code берёт из ~/.claude.json и .mcp.json в корне проекта. Файлы ~/.claude/mcp.json, ~/.claude/.mcp.json и %APPDATA%\Claude\mcp.json он не читает. В трекере есть обращение #5037: конфиг положили в .claude/.mcp.json, и из шести серверов загрузился один.

Как устроен файл .mcp.json?

Коротко: Файл .mcp.json - текстовый список серверов в корне проекта, записанный в формате JSON. Его пишет команда с флагом --scope project, можно и руками. Файл уходит в общий репозиторий, поэтому при первом запуске Claude Code спрашивает, подключать ли сервер. Ключи в него не пишут.

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

У сервера с url поле type обязательно, без него запись пропускается. Файл читается при старте сессии, после правки перезапусти claude. Подтверждение нужно, чтобы чужой репозиторий не запускал программы без спроса, сбросить решения можно командой claude mcp reset-project-choices.

Ключи заменяют подстановкой: ${API_KEY} берёт значение из окружения, ${API_KEY:-значение} даёт запасное. Собственные ключи Claude Code вроде ANTHROPIC_API_KEY в адрес удалённого сервера не подставляются, чтобы чужой конфиг их не отправил. Блок mcpServers из инструкции для Claude Desktop переносится командой claude mcp add-json, а настроенные там серверы - командой claude mcp add-from-claude-desktop (macOS и WSL).

Как войти в сервер, который просит авторизацию?

Коротко: Облачные сервисы вроде Notion и Sentry пускают агента после входа через браузер по протоколу OAuth. Сервер добавляется обычной командой, получает статус Needs authentication, а вход проходит из панели /mcp или командой claude mcp login. Постоянный ключ передаётся заголовком.

Команда для Notion, одна и та же у Anthropic и у Notion:

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

Дальше claude, /mcp, выбрать notion, Enter, пункт Authenticate и подтверждение в браузере. С версии 2.1.186 то же делает claude mcp login notion, флаг --no-browser печатает адрес для входа, если браузера нет. Токены Claude Code обновляет сам, отзывает их claude mcp logout notion.

Я проверил адреса командой curl -I, как советует документация: сервер документации ответил 405, Notion и GitHub - 401. Код 405 значит «сервер на месте», 401 - «на месте и ждёт входа».

Пример с токеном из документации Anthropic - GitHub:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer YOUR_GITHUB_PAT"

Ключ при добавлении не проверяется: с заглушкой в /mcp будет failed с кодом вроде 401. Без команд: коннекторы с claude.ai/customize/connectors появляются в Claude Code сами, если ты вошёл аккаунтом claude.ai. Gmail, Google Calendar и Microsoft 365 подключаются только так.

Живой пример - ClaudeBase. База работает как MCP-сервер agent.claudebase.ru, код подключения подписчик получает вместе с доступом. Хватает одной команды в Claude Code или Codex, дальше материалы агент ищет и берёт сам, а каталог пополняется. Рядом лежат разборы «Настройки Claude Code, Codex и VS Code» и «Хуки: если случилось X - сделай Y», видеоурок «Рабочее окружение: правила проекта и разрешения». Посмотреть, что входит в доступ.

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

Коротко: Первым подключи сервер без входа, чтобы проверить механизм, дальше - сервисы, из которых ты сейчас копируешь данные в чат. Ниже четыре сервера с командами из официальных инструкций. Из чужих подборок бери только то, что автор ещё поддерживает.

Сервер	Что даёт агенту	Чей	Вход	Команда
Документация Claude Code	поиск по документации агента	Anthropic	не нужен	`claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp`
Playwright	браузер: открыть, нажать, прочитать	Microsoft	не нужен, Node.js 18+	`claude mcp add playwright -- npx -y @playwright/mcp@latest`
Notion	чтение и правка страниц	Notion	OAuth через `/mcp`	`claude mcp add --transport http notion https://mcp.notion.com/mcp`
GitHub	задачи, запросы на слияние, код	GitHub	токен в заголовке	`claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer YOUR_GITHUB_PAT"`

Playwright открывает окно браузера, за которым можно следить, версия на npm 21 сентября 2026 года - 0.0.82. В README авторы оговаривают, что кодовым агентам бывает выгоднее их CLI со скиллами: меньше токенов.

Notion работает только после входа, старый открытый notion-mcp-server компания больше не развивает. Для GitHub документация Anthropic советует fine-grained токен с доступом к нужным репозиториям. Инструкция GitHub предлагает ещё вариант через claude mcp add-json, который на Windows может ответить Invalid input.

В README эталонных серверов MCP серверы GitHub, Puppeteer, Slack, PostgreSQL, SQLite и Brave Search перенесены в архив, а старые подборки до сих пор советуют их пакеты. Новые серверы ищи в каталоге Anthropic Directory, любой удалённый оттуда добавляется той же командой. Playwright, Notion и GitHub есть и в виде плагинов официального каталога Anthropic, об этом - плагины для Claude Code.

Сколько места в контексте занимают серверы?

Коротко: Каждый сервер MCP в Claude Code занимает часть окна контекста в каждой сессии: туда попадают имена его инструментов и инструкции. Полные описания по умолчанию подгружаются по требованию. Сколько занимает каждый сервер, показывает /context, а лишний выключает /mcp disable.

/mcp disable notion

Ответ инструмента больше 10 000 токенов вызывает предупреждение, по умолчанию в разговор пропускается до 25 000 токенов, а ответ больше предела сохраняется в файл. Субагенты получают все MCP-инструменты основной сессии, так что лишние серверы выключай до их запуска, подробнее - агенты Claude Code. Расход целиком разобран в статье Claude Code: лимиты и расход.

Чем рискуешь, подключая чужой сервер?

Коротко: MCP-сервер - чужой код или чужой облачный сервис, которому агент отдаёт твои данные. Anthropic проверяет коннекторы для своего каталога, но прямо пишет, что не проводит аудит безопасности ни одного MCP-сервера. Доверять ли серверу, решаешь ты, до подключения.

Локальный сервер работает с твоими правами. Спецификация MCP разбирает строку запуска, которая вместе с пакетом отправляет наружу ключ SSH.
Внедрение инструкций. Сервер, который приносит страницы или письма, может принести и спрятанную в них команду, документация Anthropic об этом предупреждает.
Ключи в общем файле. Токен в .mcp.json уедет в репозиторий. Для ключей есть ${ПЕРЕМЕННАЯ} и область local.
Лишние права. Токену хватает доступа к нужным репозиториям, базе данных - пользователя только на чтение.

В обычной сессии серверы из .mcp.json не запускаются без подтверждения, новые серверы проходят проверку доверия. Инструменты разрешаются правилами: mcp__notion__* - все инструменты сервера notion, а mcp__* в запретах выключает все MCP-инструменты. Как задавать правила через /permissions, разобрано в статье про настройку Claude Code.

Частые ошибки подключения

Коротко: Почти все поломки сводятся к пяти причинам: другая папка, ошибка в адресе или команде, нет входа, медленный старт, конфиг не на месте. Ниже тексты сообщений так, как их показывает Claude Code. Разбор начинай с claude mcp get.

No MCP servers configured

Панель /mcp не нашла серверов для этой папки: сервер добавлен в другом проекте, конфиг лежит не там или запись испорчена. Добавь сервер из текущей папки или с --scope user.

Failed to connect

Сервер не запустился или не ответил, код ответа видно в claude mcp get с версии 2.1.219. Локальный сервер запусти руками:

npx -y @playwright/mcp@latest

Ждёт ввода - сервер рабочий, сверь команду в claude mcp get: возможно, потеряно двойное тире. Падает - сообщение назовёт, чего нет. Если первый запуск через npx дольше 30 секунд, подними предел:

MCP_TIMEOUT=60000 claude

Нет ответа на curl -I - проверь адрес и сеть, про сеть из России есть статья Claude Code в России.

MCP server sentry already exists in local config

Сервер с этим именем уже есть в этой области, вместо sentry будет твоё имя. Удали запись через claude mcp remove или возьми другое имя.

MCP endpoint not found at

MCP endpoint not found at <origin>. Check the URL in your MCP config.

Путь в адресе неверный, сверь его в claude mcp get с инструкцией сервера.

has a “url” but no “type”

MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry

Допиши в .mcp.json строку "type": "http".

MCP server "<name>" needs you to sign in again (run /mcp to re-authenticate)

Вход истёк посреди сессии: открой /mcp и войди заново.

is Anthropic-hosted and doesn’t support local OAuth

Такой ответ приходит на попытку войти в Gmail, Google Calendar или Microsoft 365, добавленные своей командой. Эти сервисы подключаются в коннекторах claude.ai.

missing required argument ‘name’

Ошибка из инструкции GitHub для PowerShell: имя сервера ставится сразу после claude mcp add, флаги - за ним.

Чек-лист

Коротко: Подключение MCP в Claude Code закончено, когда сходятся шесть пунктов ниже. Каждый проверяется командой или взглядом на панель /mcp, а каждый несошедшийся пункт разобран в своём разделе.

claude mcp list показывает сервер со статусом ✔ Connected.
claude mcp get показывает задуманную область: local, project или user.
Сервер с входом прошёл его, статус Needs authentication пропал.
Агент выполнил запрос через сервер, вызов подписан его именем.
В .mcp.json нет токенов, вместо них ссылки ${ПЕРЕМЕННАЯ}.
Ненужные серверы выключены через /mcp disable или удалены.

Сервер подключён - что дальше?

Коротко: Один рабочий сервер значит, что механизм проверен, дальше его расширяют под свои задачи. Ниже три ближайших шага и соседние статьи, где разобрано то, что сюда не поместилось.

Подключи сервис, из которого ты чаще всего копируешь данные в чат.
Задай разрешения на его инструменты через /permissions.
Запиши в файл правил CLAUDE.md, когда агенту звать сервер: «задачи смотри в Notion через сервер notion».

Рядом: плагины для Claude Code - серверы вместе со скиллами, команды Claude Code - шпаргалка с /mcp, агенты Claude Code - субагенты, которые наследуют твои серверы.

Проверенные правила, скиллы и настройки можно не собирать по одному. ClaudeBase подключается тем же способом: агент получает базу как MCP-сервер и сам изучает её, когда задача этого требует. Как получить подключение к ClaudeBase.

MCP в Claude Code