SpyBara
Go Premium

mcp-quickstart.md 2026-10-19 23:58 UTC to 2026-10-20 23:00 UTC

This page contains 215 additions and 249 deletions.

2026
Thu 1 23:59 Thu 15 23:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Wed 28 23:57 Fri 30 23:01

Подключение к серверам MCP

Добавьте сервер MCP в Claude Code, проверьте соединение и найдите конфигурацию на диске.

Model Context Protocol (MCP) позволяет Claude Code использовать инструменты, выходящие за рамки встроенного набора, такие как поиск в трекере проблем, запрос к базе данных или управление веб-браузером. Эти инструменты поступают от серверов MCP, которые работают на вашем компьютере или как размещённые сервисы.

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

[!NOTE]

Вы также можете добавлять серверы MCP с других поверхностей, включая настольное приложение, VS Code и веб-версию. См. Подключение с других поверхностей.

Для каждого способа подключения и настройки серверов MCP в Claude Code см. справочник MCP.

Перед началом

Убедитесь, что у вас есть:

  • Claude Code установлен и аутентифицирован
  • Открытый терминал в каталоге проекта. Подойдёт любой каталог, включая пустой.

Добавление и проверка сервера

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

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

1. Добавление сервера MCP

Зарегистрируйте сервер в Claude Code. Запустите это в вашем терминале, не внутри сеанса claude: вы настраиваете сервер перед началом разговора.

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

Части команды:

  • claude mcp add: регистрирует сервер в Claude Code.
  • --transport http: сервер размещён по URL, а не запущен как локальный процесс.
  • claude-code-docs: имя, которое вы придумываете. Вызов того же сервера docs работал бы идентично. Claude Code использует любое имя, которое вы выберете, для обозначения инструментов сервера в выводе Claude и для ссылки на сервер в командах, таких как claude mcp remove.
  • https://code.claude.com/docs/mcp: URL, где размещён сервер.

Команда выводит подтверждение вроде Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to local config, за которым следует строка File modified:, показывающая файл конфигурации, который она записала. Часть local config означает, что сервер зарегистрирован для вас в этом проекте: если вы запустите Claude Code в другом проекте, этот сервер там не активен. Чтобы зарегистрировать сервер один раз для всех ваших проектов, добавьте его в область пользователя, что рассмотрено в Изменение области сервера.

2. Проверка статуса соединения

Подтвердите, что сервер появляется в вашем списке серверов и проверьте его статус:

claude mcp list

Сервер появляется с индикатором статуса:

Статус Значение
✔ Connected Готов к использованию. Это то, что вы должны увидеть для claude-code-docs
! Connected · tools fetch failed Сервер подключился, но не смог получить список своих инструментов. Запустите claude mcp get <name> для получения деталей ошибки
! Needs authentication Сервер доступен, но требует входа в браузер или токена, переданного с --header. См. Подключение сервера, требующего входа
✘ Failed to connect Сервер не ответил. См. Troubleshooting
✘ Connection error Попытка соединения выдала ошибку. См. Troubleshooting
⏸ Pending approval (run `claude` to approve) Сервер в области проекта, который вы ещё не одобрили. См. Редактирование .mcp.json напрямую
⊘ Disabled for this project (re-enable via /mcp) Сервер отключён для этого проекта списком disabledMcpServers проекта. См. Отключение сервера без его удаления

Некоторые устаревшие консоли Windows, такие как консоль по умолчанию на Windows 10, не поддерживают эти глифы Unicode и показывают √ и × вместо ✔ и ✘.

3. Использование сервера

Начните сеанс и попросите Claude использовать новый сервер по имени:

claude

Use the claude-code-docs server to look up what MCP_TIMEOUT does

[!NOTE]

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

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

4. Удаление сервера

Этот шаг необязателен. Когда вы закончите экспериментировать, вы можете удалить сервер:

claude mcp remove claude-code-docs

Команда подтверждает с Removed MCP server "claude-code-docs" from local config и строкой File modified:, показывающей файл, который она обновила.

[!NOTE]

Каждый подключённый сервер занимает некоторое место в контекстном окне Claude, потому что имена его инструментов и инструкции сервера загружаются в каждый сеанс. Удаление серверов, которые вы больше не используете, освобождает это место.

Где сохраняются серверы

Команда claude mcp add записывает детали сервера в файл конфигурации. По умолчанию она регистрирует сервер в области local: приватно для вас, активно только в текущем проекте. Передайте --scope user для регистрации один раз для всех ваших проектов или --scope project для совместного использования с товарищами по команде. Изменение области сервера проходит через оба варианта.

[!NOTE]

claude mcp add работает одинаково в каждой оболочке, включая PowerShell и Command Prompt. Внутри сеанса claude используйте команду /mcp для проверки и управления серверами, которые вы уже добавили.

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

Поиск вашей конфигурации на диске

Команда claude mcp add записывает сервер в одну из трёх областей, сохранённых в двух файлах, в зависимости от флага --scope. Вам не нужно редактировать эти файлы напрямую, но знание того, где они находятся, помогает при отладке и контроле версий.

Область Файл Доступно для
local ~/.claude.json, под записью для этого проекта Только вам, только этот проект. По умолчанию
project .mcp.json в корне вашего проекта Всем, кто клонирует проект
user ~/.claude.json, под ключом верхнего уровня mcpServers Только вам, все проекты

На Windows ~/.claude.json разрешается в %USERPROFILE%\.claude.json, обычно C:\Users\YourName\.claude.json. Если вы установили CLAUDE_CONFIG_DIR, Claude Code читает .claude.json из этого каталога вместо этого.

Запустите claude mcp get claude-code-docs для просмотра того, какая область содержит определение сервера. Для того, как области взаимодействуют, когда один и тот же сервер определён в более чем одной, см. Области установки MCP.

Изменение области сервера

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

claude mcp remove claude-code-docs --scope local

Использование сервера во всех ваших проектах

Повторно добавьте сервер в области user, чтобы сделать его активным в каждом проекте, который вы открываете, оставаясь приватным для вас:

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

Совместное использование сервера с вашей командой

Повторно добавьте сервер в области project, который записывает в .mcp.json в корне проекта:

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

Зафиксируйте .mcp.json в контроле версий. Товарищи по команде, которые клонируют репозиторий и запускают Claude Code, видят приглашение одобрить сервер, затем он подключается и для них.

Дополнительные примеры серверов MCP

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

Добавление локального сервера

Локальный сервер stdio — это программа, которую Claude Code запускает как подпроцесс на вашем компьютере, а не сервис, к которому он обращается по URL. Используйте один для инструментов, которым требуется доступ к локальным ресурсам, таким как браузер, ваша файловая система или сокет базы данных.

Сервер Playwright MCP — хороший для попытки: он даёт Claude браузер, который он может навигировать, нажимать и читать, и он не требует учётной записи. Он работает через npx, поэтому требует Node.js 18 или позже.

1. Добавление сервера Playwright

Зарегистрируйте сервер с командой, которую Claude Code должен запустить для его запуска:

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

Эта команда отличается от размещённого примера тремя способами:

  • Нет флага --transport, потому что локальные серверы используют транспорт stdio по умолчанию.
  • Всё после разделителя -- — это команда, которую Claude Code запускает для запуска сервера.
  • -y говорит npx установить пакет без запроса.

Команда выводит подтверждение вроде Added stdio MCP server playwright with command: npx -y @playwright/mcp@latest to local config, за которым следует строка File modified:, показывающая файл конфигурации, который она записала.

Playwright управляет любым Chrome, уже установленным на вашем компьютере. Чтобы использовать другой браузер, добавьте --browser с именем браузера, например --browser firefox, после @playwright/mcp@latest.

2. Проверка соединения

Подтверждение Added означает, что запись была сохранена, а не то, что команда работает. Проверьте соединение:

claude mcp list

Первая проверка может показать ✘ Failed to connect, пока npx загружает пакет, поэтому подождите момент и запустите её снова. После завершения загрузки статус изменяется на ✔ Connected. Если он по-прежнему показывает ✘ Failed to connect после пары повторных попыток, см. Troubleshooting.

3. Использование браузера

Дайте Claude задачу, которая требует браузер:

Use playwright to open https://example.com and tell me the page title

Окно браузера открывается, чтобы вы могли наблюдать, как оно работает, и вызовы инструментов в выводе Claude помечены именем сервера playwright и действием, например browser_navigate.

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

Подключение сервера, требующего входа

Размещённые сервисы, такие как Sentry, Linear и Notion, запускают свои серверы MCP за OAuth: вы добавляете URL сервера, затем входите через ваш браузер.

Шаги ниже используют Sentry в качестве примера. Чтобы подключить другой сервис, замените его URL, который вы можете найти в Справочнике Anthropic или документации сервиса.

1. Добавление сервера

Команда add такая же, как для сервера документации, с URL Sentry:

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

После добавления claude mcp list показывает сервер с ! Needs authentication. Это ожидаемо: следующий шаг завершает вход.

2. Аутентификация в вашем браузере

Начните сеанс Claude Code и откройте панель MCP:

/mcp

Выберите sentry из списка, нажмите Enter и выберите Authenticate. Ваш браузер открывается на странице входа Sentry. Одобрите соединение там.

Вернувшись в Claude Code, статус сервера изменяется на подключённый. Если вход не удаётся или браузер не открывается, см. Troubleshooting.

3. Использование сервера

Спросите Claude что-то, что требует сервис, например What Sentry projects do I have access to?, и ищите вызовы инструментов, помеченные именем сервера sentry в его выводе.

Серверы, которые аутентифицируются со статическим токеном вместо OAuth, принимают токен во время добавления с --header "Authorization: Bearer <token>". См. пример GitHub для рабочей версии.

Редактирование .mcp.json напрямую

Каждый файл в таблице областей использует один и тот же формат JSON для записей сервера. Этот раздел редактирует .mcp.json, файл области проекта. Это тот, который наиболее стоит писать вручную, потому что он проверяется в репозитории, где он удваивается как конфигурация-как-код для вашей команды.

Создайте .mcp.json в корне вашего проекта. Пример ниже определяет оба сервера из этого руководства, размещённый сервер документации, доступный по HTTP, и сервер Playwright как локальный процесс stdio:

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

Поля отличаются по типу сервера:

  • Для HTTP-серверов url — это конечная точка, к которой подключается Claude Code.
  • Для серверов stdio command и args — это программа, которую он запускает.

После сохранения файла начните новый сеанс Claude Code в проекте. Claude Code читает .mcp.json при запуске.

В первый раз, когда Claude Code видит сервер в области проекта, он просит вас одобрить его. Приглашение существует, чтобы репозиторий, который вы клонируете, не мог запускать процессы на вашем компьютере без вашего согласия. Одобрите приглашение или запустите /mcp для одобрения позже, если вы его пропустили.

После одобрения запустите /mcp и проверьте, что серверы показаны как подключённые. Если один показывает ошибку вместо этого, см. Troubleshooting.

Подключение с других поверхностей

Это руководство использует команды CLI claude mcp, но каждая поверхность Claude Code может подключаться к серверам MCP:

Troubleshooting

Если сервер не подключается, проверьте его статус с /mcp внутри сеанса или claude mcp list из вашей оболочки, затем сопоставьте симптом ниже. Панель /mcp также позволяет вам переподключиться или аутентифицироваться без выхода из сеанса.

/mcp shows No MCP servers configured

Claude Code не нашёл никаких серверов для текущего каталога. Наиболее распространённые причины:

  • Вы запустили claude mcp add из другого проекта. Серверы в области local привязаны к проекту, где вы их добавили: корень репозитория или точный каталог, если вы не были в репозитории git. Повторно добавьте сервер из проекта, в котором вы находитесь сейчас, или добавьте его с --scope user, чтобы он не был привязан к проекту.
  • Вы отредактировали файл конфигурации по неправильному пути. Правильные файлы — это ~/.claude.json и <project>/.mcp.json. Claude Code не читает пути, такие как ~/.claude/.mcp.json, ~/.claude/config/mcp.json, ~/.claude/mcp.json или %APPDATA%\Claude\mcp.json. Для серверов в области user запустите claude mcp add --scope user, который записывает в ключ mcpServers в ~/.claude.json; для серверов в области project отредактируйте .mcp.json в корне проекта.
  • Вы написали неправильную запись в .mcp.json. Claude Code пропускает эту запись и всё ещё загружает остальные. Запустите claude mcp list из вашей оболочки и ищите предупреждение о разборе, которое называет проблемное поле.

Status shows Failed to connect or Connection error

Оба статуса означают, что сервер не запустился или URL не ответил. Они также могут появляться для HTTP-серверов, которые отклоняют токен, который вы настроили в headers.Authorization; сервер, который хочет токен, который вы не настроили, показывает ! Needs authentication вместо этого, рассмотренный в Подключение сервера, требующего входа.

Ваш первый шаг зависит от того, какой статус вы видите:

  • Failed to connect: начните с деталей сбоя на самом статусе. claude mcp list и claude mcp get <name> показывают HTTP-статус или код ошибки и любой текст ошибки, который вернул сервер, что часто называет проблему напрямую, такую как отсутствующий заголовок или отклонённый токен. До версии 2.1.219 Failed to connect показывал только простой статус, и вам нужны были проверки curl и команд позже в этом разделе, чтобы найти причину.
  • Connection error: Claude Code не добавляет никаких деталей к этому статусу ни в какой версии, поэтому переходите прямо к проверкам curl и команд позже в этом разделе.

Если деталь указывает на учётные данные или URL, также проверьте предупреждения в выводе claude mcp list. Claude Code отмечает значения конфигурации со скрытыми ведущими или конечными пробелами, частую причину сбоев аутентификации после вставки токена.

Если HTTP-сервер возвращает 404 Not Found, Claude Code показывает MCP endpoint not found at <origin>. Check the URL in your MCP config. когда вы выбираете сервер в /mcp. Сообщение называет происхождение URL, такое как https://mcp.example.com, без его пути, поэтому запустите claude mcp get <name>, чтобы увидеть полный URL, который вы настроили. Сравните его путь с документированным путём конечной точки MCP сервера, затем запустите claude mcp remove <name> и повторно добавьте с правильным URL. До версии 2.1.219 сообщение включало путь URL, а до версии 2.1.191 404 показывал общее сообщение Error POSTing to endpoint без URL.

Для HTTP-серверов подтвердите, что URL доступен с вашего компьютера:

curl -I https://mcp.sentry.dev/mcp

В PowerShell используйте curl.exe вместо curl, чтобы запрос шёл к реальному двоичному файлу curl, а не к псевдониму Invoke-WebRequest.

Ответ говорит вам, какой вид проблемы у вас есть:

  • 404 или 405: сервер работает. Многие конечные точки MCP отвечают только на POST-запросы, поэтому это всё ещё подтверждает, что URL доступен с вашего компьютера.
  • 401 или 403: сервер работает и вам нужно аутентифицироваться. Используйте вход в браузер в Подключение сервера, требующего входа, или для серверов, которые принимают токен вместо этого, например GitHub, передайте его с --header "Authorization: Bearer <token>" в команде claude mcp add.
  • Нет ответа вообще: проверьте URL и вашу сеть.

Для серверов stdio запустите настроенную команду непосредственно в вашем терминале, чтобы увидеть основную ошибку. Для сервера Playwright из этого руководства запустите:

npx -y @playwright/mcp@latest

То, что происходит дальше, говорит вам, где находится проблема:

  • Команда запускается и ждёт ввода: сам сервер работает.

    Запустите claude mcp get <name> и подтвердите, что команда, показанная там, совпадает с тем, что вы только что запустили. Если показанная команда отличается от того, что вы набрали, вы, вероятно, пропустили разделитель -- перед командой сервера. Удалите сервер и повторно добавьте его с -- на месте. Если вы написали .mcp.json вручную, проверьте его синтаксис и местоположение. До версии 2.1.285 claude mcp get не печатал строку Command для записи stdio, сохранённой без поля type, такой как запись .mcp.json, написанная вручную. На этих версиях запустите claude mcp list вместо этого, который печатает командную строку в любом случае.

  • Команда выдаёт ошибку: сообщение называет то, что отсутствует, такое как Node.js или браузер.

Connection timed out at startup

Сервер занял больше времени, чем стандартное время ожидания запуска в 30 секунд. Первый запуск сервера stdio может быть медленным, пока npx загружает пакет. Увеличьте лимит с переменной окружения MCP_TIMEOUT, в миллисекундах:

MCP_TIMEOUT=60000 claude

В PowerShell установите переменную перед командой на той же строке:

$env:MCP_TIMEOUT = "60000"; claude

До версии 2.1.299 некоторые подключения к работающим HTTP-серверам завершались по таймауту при запуске независимо от MCP_TIMEOUT. Если вы используете одну из этих версий и работающий HTTP-сервер всё ещё завершается по таймауту после увеличения лимита, обновите Claude Code.

Server already exists

Вы уже добавили сервер с этим именем в той же области. Либо удалите существующую запись сначала, либо выберите другое имя:

claude mcp remove claude-code-docs

Если имя существует в более чем одной области, remove сообщает exists in multiple scopes. Передайте --scope для выбора того, какую копию удалить, например claude mcp remove claude-code-docs --scope local.

Server connects but no tools appear

Запустите /mcp внутри сеанса и выберите сервер, чтобы увидеть его список инструментов. Если список пуст, сервер запустился, но не зарегистрировал никаких инструментов, что обычно означает, что ему не хватает требуемой переменной окружения, такой как ключ API.

Передайте переменную с --env KEY=value на claude mcp add, или в поле env записи сервера в .mcp.json. Документация сервера перечисляет переменные, которые ему нужны.

До версии 2.1.302 /mcp показывал статус tools fetch failed для сервера, использующего ревизию протокола 2026-07-28, который не включал resultType, ttlMs или cacheScope в свои ответы. Если вы используете одну из этих версий и сервер показывает этот статус, обновите Claude Code.

Changes to .mcp.json don't take effect

Claude Code читает .mcp.json при запуске сеанса. Выйдите и перезапустите сеанс после редактирования файла.

Если ваши серверы всё ещё не появляются, запустите claude mcp list и ищите предупреждение о разборе. Claude Code пропускает неправильно сформированные записи и показывает там проблемное поле.

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

claude mcp reset-project-choices

OAuth sign-in fails or browser doesn't open

Запустите /mcp, выберите сервер и выберите Authenticate снова. Если браузер не открывается автоматически, скопируйте URL, показанный в терминале, и откройте его вручную. См. Аутентификация с удалёнными серверами MCP для фиксированных портов обратного вызова и предварительно настроенных учётных данных.

Следующие шаги

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