mcp claude code: что это такое и как подключить серверы по шагам

mcp claude code — это способ дать агенту доступ к тому, что лежит за пределами папки проекта: браузеру, github, макетам figma, базе данных. сервер подключается одной командой claude mcp add в обычном терминале, а проверяется через claude mcp list и /mcp внутри сессии. ниже — как это устроено, команды строго по документации anthropic, семь серверов для вайбкодера и случаи, когда mcp лишний.

mcp claude code простыми словами: протокол, сервер, инструменты

mcp (model context protocol) — открытый стандарт, по которому ии-приложения подключаются к внешним системам. на сайте протокола его сравнивают с разъёмом usb-c: один стандартный порт, к которому подходят разные устройства. сервис один раз делает mcp-сервер, и с ним работают claude, cursor, vs code и другие клиенты.

в этой схеме три роли. клиент — сам claude code, он решает, когда и что вызвать. сервер — программа на твоём компьютере или веб-сервис, который отдаёт агенту набор возможностей. возможности бывают трёх видов:

• инструменты — действия: открыть страницу, завести issue, выполнить sql-запрос;
• ресурсы — данные, на которые можно сослаться через @, как на файл, например @github:issue://123;
• промпты — готовые команды сервера, они появляются в списке по /, например /mcp__github__list_prs.

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

в поиске часто пишут просто «mcp claude» — это то же самое. протокол один: коннекторы, добавленные на claude.ai, сами появляются в claude code, если ты вошёл тем же аккаунтом.

транспорты: http, stdio и что устарело

сервер может жить в интернете или у тебя на компьютере. от этого зависит транспорт — способ, которым claude code с ним общается.

с версии 2.1.265 claude code сам переключается с http на sse, если сервер не принимает http.

как подключить mcp к claude code: первый сервер по шагам

как поставить самого агента, я разобрал в статье как установить claude code на windows и mac. дальше всё делается в обычном терминале, не внутри сессии claude. для первой пробы anthropic предлагает собственный сервер с поиском по документации claude code — он не требует ни входа, ни ключей.

шаг 1. добавь сервер. имя claude-code-docs придумываешь сам: под ним сервер будет виден в командах и в ответах агента.

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

в ответ придёт строка Added HTTP MCP server ... to local config. это значит, что сервер записан для тебя и только в этом проекте.

шаг 2. проверь статус. команда add только сохраняет настройки и не проверяет ключи, поэтому смотреть, работает ли сервер, нужно отдельно:

claude mcp list

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

шаг 3. попроси агента им воспользоваться. запусти claude и напиши что-то вроде «найди через сервер claude-code-docs, что делает MCP_TIMEOUT». при первом вызове агент спросит разрешение. вызовы в выводе подписаны именем сервера — так видно, что ответ пришёл от него, а не из памяти модели.

шаг 4. убери лишнее. подробности по серверу — claude mcp get имя, удаление — claude mcp remove:

claude mcp get claude-code-docs
claude mcp remove claude-code-docs

по документации claude mcp add одинаково работает во всех оболочках, включая powershell и командную строку windows.

локальный сервер через stdio и двойной дефис

локальный сервер claude code запускает сам, как процесс. порядок такой: опции claude code, имя, потом -- и команда запуска. всё после двойного дефиса уходит серверу без изменений. без него claude code примет флаги сервера, вроде -y или --port, за свои и команда сломается.

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

ключи передаются через --env до двойного дефиса. есть тонкость: если сразу после --env стоит имя сервера, cli примет его за ещё одну пару «ключ=значение», поэтому между ними ставят другую опцию:

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

области видимости: local, project, user

флаг --scope решает, в каких проектах сервер загружается и увидят ли его коллеги.

на windows ~/.claude.json — это %USERPROFILE%\.claude.json. local подходит для экспериментов и серверов с личными ключами, которые не должны попасть в git. user — для того, что нужно везде, например браузера. project — когда над проектом работает команда и всем нужен одинаковый набор.

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

если один и тот же сервер описан в нескольких местах, побеждает local, за ним project, user, серверы из плагинов и в конце коннекторы claude.ai. запись берётся целиком, поля из разных мест не склеиваются. сменить область у готового сервера нельзя: удаляешь его и добавляешь заново с другим --scope.

файл .mcp.json и где держать ключи

.mcp.json — это настройка в виде кода: файл лежит в репозитории, и каждый, кто откроет проект, получит те же серверы. его можно писать руками в том же формате, который создаёт claude mcp add --scope project:

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

что здесь важно:

• ключи в файл не пиши. ${VAR} подставляет переменную окружения, ${VAR:-default} — значение по умолчанию, если переменной нет. подстановка работает в полях command, args, env, url и headers.
• у записи с url обязательно поле "type". без него claude code считает сервер локальным и пропускает его с ошибкой.
• учётные данные самого claude code, например ANTHROPIC_API_KEY, в url и заголовках удалённого сервера читаются как пустые. так чужой .mcp.json не отправит твой доступ на свой сервер.
• файл читается при старте сессии: после правки перезапусти claude code.
• при первом запуске агент спросит, одобряешь ли серверы из этого файла. сбросить ответы — claude mcp reset-project-choices.

авторизация: oauth и токены

многие облачные серверы просят войти в аккаунт. claude code поддерживает oauth 2.0: добавляешь сервер по url, в сессии открываешь /mcp, выбираешь сервер и пункт authenticate, дальше входишь в браузере. токены хранятся в защищённом хранилище и обновляются сами, отозвать доступ можно пунктом clear authentication в том же меню.

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
claude mcp login sentry

claude mcp login проводит тот же вход из оболочки, а без браузера, например по ssh, печатает ссылку для входа.

второй вариант — постоянный токен в заголовке. так работает удалённый сервер github: personal access token передаётся через --header. если сервер такой заголовок отверг, claude code не переключится на oauth, а покажет ошибку подключения.

лучшие mcp для claude: 7 серверов для вайбкодера

каталогов «claude mcp servers» в сети много, но я беру только серверы, у которых есть официальная страница с инструкцией от самого сервиса. проверенные коннекторы anthropic собирает в каталоге на claude.ai/directory, и любой удалённый сервер оттуда добавляется той же claude mcp add. если ты ещё выбираешь сам инструмент, сначала загляни в обзор ии для вайбкодинга.

1. playwright — браузер для проверки сайта

сервер от microsoft даёт агенту браузер: открыть страницу, кликнуть, заполнить форму, прочитать результат. он работает с деревом доступности страницы, а не со скриншотами, поэтому модель со зрением не нужна. нужен node.js 18 или новее, аккаунт не нужен. по умолчанию окно браузера открыто, и видно, что делает агент.

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

2. context7 — свежая документация библиотек

context7 подтягивает в промпт документацию и примеры кода под нужную версию библиотеки, чтобы агент не писал по устаревшему api. установщик входит через oauth, создаёт ключ и предлагает выбрать режим: mcp или cli со скиллом. ключ не обязателен, но бесплатный ключ даёт больше запросов. для ручной настройки есть адрес https://mcp.context7.com/mcp с ключом в заголовке.

npx ctx7 setup --claude

3. github — репозитории, issues и pull request

официальный сервер github. удалённая версия работает по токену: в настройках github создаёшь fine-grained token с доступом только к тем репозиториям, где будет работать агент. у сервера есть режим только для чтения, в нём инструменты записи отключены, и наборы инструментов, чтобы включать только нужное.

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

4. figma — код по макету

сервер figma даёт агенту контекст макета: компоненты, переменные, разметку. работает и в обратную сторону — создаёт и меняет объекты прямо на холсте. версий две, удалённая и десктопная. сама figma советует удалённую и ставит её через плагин, в котором уже лежат настройки сервера и скиллы:

claude plugin install figma@claude-plugins-official

потом перезапусти claude code, открой /plugin, вкладку installed, выбери figma и подтверди доступ в браузере.

5. supabase — база и бэкенд

если проект на supabase, через сервер агент работает с базой, отладкой и edge functions. supabase предлагает добавлять сервер в область project:

claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp"

к адресу можно дописать параметры: read_only=true выполняет все запросы от пользователя postgres с правами только на чтение, project_ref ограничивает сервер одним проектом. к рабочему проекту с живыми данными supabase советует подключаться, только когда без этого никак.

6. postgres и другие базы через dbhub

для своей базы в документации claude code в пример взят dbhub от bytebase: он подключает реляционную базу по строке подключения. anthropic прямо советует указывать в ней пользователя только для чтения, чтобы запросы агента не могли изменить данные.

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

7. sentry — ошибки с живого сайта

если сайт уже работает и ошибки собирает sentry, сервер даёт агенту доступ к ним: агент сам смотрит события, а не ждёт, пока ты скопируешь их в чат. подключается по url и входу через oauth, команда — в разделе выше.

про blender, который тоже часто ищут вместе с mcp: у blender lab есть официальный mcp-сервер для blender 5.1 и новее — это аддон плюс отдельный сервер. авторы предупреждают: сервер выполняет сгенерированный ии код без всякой защиты, поэтому запускать его стоит в виртуальной машине или на системе без важных данных.

безопасность: prompt injection и доверие к серверам

mcp-сервер — это код или сервис, которому ты открываешь свои данные и аккаунты. документация claude code говорит прямо: до подключения убедись, что доверяешь серверу. серверы, которые тянут внешний контент — страницы, письма, тикеты, — открывают дорогу prompt injection. чужой текст с инструкциями попадает к агенту, и тот может принять его за задачу.

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

ещё одна деталь: anthropic проверяет коннекторы перед добавлением в свой каталог, но не проводит аудит безопасности и не управляет ни одним mcp-сервером. поэтому совет из документации — писать серверы самому или брать у поставщиков, которым доверяешь. правила, которые из этого следуют:

• ставь серверы со страницы самого сервиса, а не из случайного списка;
• для баз — пользователь только на чтение и, где можно, копия базы, а не рабочая;
• токены — с минимальными правами и только на нужные репозитории;
• не отключай подтверждение вызовов, пока сервер для тебя новый;
• читай .mcp.json чужого репозитория, прежде чем одобрить серверы. окно одобрения как раз нужно, чтобы склонированный проект не запустил процессы на твоём компьютере без спроса.

в запусках claude -p и облачных сессиях этого окна нет: серверы проекта загружаются без вопросов. заблокировать их там можно через disabledMcpjsonServers в настройках или флаг --strict-mcp-config.

когда mcp не нужен и хватит cli

mcp — не обязательный шаг. claude code и так запускает команды в терминале, поэтому если у сервиса есть консольная утилита, агент часто справится через неё. даже авторы playwright mcp пишут в описании сервера, что агентам для кода может больше подойти связка cli и скиллов: вызовы короче и не загружают в контекст большие схемы инструментов и дерево страницы. у context7 тоже есть режим cli со скиллом совсем без mcp.

вторая причина — контекст. каждый подключённый сервер занимает в нём место: имена инструментов и инструкции сервера загружаются в каждую сессию. поиск инструментов, включённый по умолчанию, подгружает полные описания только по необходимости, но длинные ответы инструментов всё равно тратят контекст: предупреждение появляется после 10 000 токенов, предел по умолчанию — 25 000 (MAX_MCP_OUTPUT_TOKENS).

я делаю через claude code сайты, ботов и seo, а этот сайт arturr_city целиком собран ии. совет у меня такой: сначала освой без mcp обычный цикл «задача — правка — проверка», о нём статья claude code как использовать. сервер добавляй, когда раз за разом носишь в чат одно и то же из другой программы или когда агенту нужен вход в аккаунт сервиса через браузер. серверы, которыми не пользуешься, удаляй.

вопросы

mcp в claude code платный?

сам протокол — открытый стандарт. за claude code ты платишь как обычно, а у сервисов за серверами свои условия: например, у context7 бесплатный ключ просто поднимает лимиты запросов.

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

начни с claude mcp list и claude mcp get: там код ошибки. адрес удалённого сервера проверь через curl -I: ответ 401 или 403 значит, что сервер жив и ждёт входа. локальный сервер запусти той же командой прямо в терминале и увидишь, чего не хватает. если первый запуск через npx не укладывается в 30 секунд, подними таймаут: MCP_TIMEOUT=60000 claude.

можно ли взять серверы из claude desktop или claude.ai?

да. claude mcp add-from-claude-desktop переносит их из приложения claude desktop на macos и в wsl. коннекторы, добавленные на claude.ai, сами доступны в claude code, если ты вошёл аккаунтом claude.ai.

источники

• connect claude code to tools via mcp — code.claude.com
• mcp quickstart — code.claude.com
• security — code.claude.com
• what is the model context protocol — modelcontextprotocol.io
• playwright mcp — github.com/microsoft
• github mcp server — github.com/github
• claude code and figma: set up the mcp server — help.figma.com
• model context protocol — supabase docs