Подключите Claude Code к инструментам через MCP

Узнайте, как подключить Claude Code к вашим инструментам с помощью Model Context Protocol.

Claude Code может подключаться к сотням внешних инструментов и источников данных через Model Context Protocol (MCP), открытый стандарт для интеграции AI с инструментами. MCP servers предоставляют Claude Code доступ к вашим инструментам, базам данных и API.

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

Если вы подключаете свой первый server, начните с MCP quickstart для пошагового руководства. Эта страница является полным справочником.

Что вы можете делать с MCP

С подключенными MCP servers вы можете попросить Claude Code:

• Реализовать функции из трекеров проблем: "Добавьте функцию, описанную в задаче JIRA ENG-4521, и создайте PR на GitHub."
• Анализировать данные мониторинга: "Проверьте Sentry и Statsig, чтобы проверить использование функции, описанной в ENG-4521."
• Запрашивать базы данных: "Найдите адреса электронной почты 10 случайных пользователей, которые использовали функцию ENG-4521, на основе нашей базы данных PostgreSQL."
• Интегрировать дизайны: "Обновите наш стандартный шаблон электронного письма на основе новых дизайнов Figma, которые были опубликованы в Slack"
• Автоматизировать рабочие процессы: "Создайте черновики Gmail, приглашающие этих 10 пользователей на сеанс обратной связи о новой функции."
• Реагировать на внешние события: MCP server также может действовать как канал, который отправляет сообщения в вашу сессию, поэтому Claude реагирует на сообщения Telegram, чаты Discord или события webhook, пока вас нет.

Поиск и создание MCP servers

Просмотрите проверенные коннекторы в Anthropic Directory. Коннекторы Directory используют ту же инфраструктуру MCP, что и Claude Code, поэтому вы можете добавить любой удаленный server из списка с помощью claude mcp add.

[!WARNING]

Убедитесь, что вы доверяете каждому server перед подключением. Servers, которые получают внешний контент, могут подвергнуть вас риску prompt injection.

Чтобы создать свой собственный server, см. руководство по MCP server для основ протокола и документацию по созданию Claude connector для аутентификации, тестирования и отправки в Directory.

Вы также можете попросить Claude создать server для вас с помощью официального плагина mcp-server-dev.

1. Установите плагин

В расширении VS Code или настольном приложении вместо этого шага следуйте инструкциям из раздела Установка плагина. В терминале запустите Claude Code командой claude, затем введите в промпт:

/plugin install mcp-server-dev@claude-plugins-official

Если установка не удается, сопоставьте сообщение, которое сообщает Claude Code:

• Marketplace "claude-plugins-official" not found: добавьте маркетплейс с помощью /plugin marketplace add anthropics/claude-plugins-official, затем повторите попытку установки.
• Plugin "<name>" not found in marketplace "claude-plugins-official": ваша локальная копия каталога маркетплейса может быть устаревшей. Обновите ее с помощью /plugin marketplace update claude-plugins-official, затем повторите попытку установки. Если при повторной попытке выводится то же сообщение, см. Плагин не найден в маркетплейсе.

Если в сводке установки указано Run /reload-plugins to apply., Claude Code затем запустит эту перезагрузку для вас. Если перезагрузка предупреждает, что ваше следующее сообщение повторно прочитает диалог, выполните /reload-plugins --force.

2. Запустите скилл сборки

/mcp-server-dev:build-mcp-server

Claude спросит о вашем варианте использования и создаст удаленный HTTP или локальный stdio server.

Установка MCP-серверов

MCP-серверы можно настроить несколькими способами в зависимости от ваших потребностей:

Вариант 1: Добавление удалённого HTTP-сервера

HTTP-серверы — рекомендуемый вариант для подключения к удалённым MCP-серверам. Это наиболее широко поддерживаемый транспорт для облачных сервисов.

# Базовый синтаксис
claude mcp add --transport http <name> <url>

# Реальный пример: подключение к Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Пример с Bearer-токеном
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

При настройке MCP-серверов через JSON в .mcp.json, ~/.claude.json или claude mcp add-json поле type принимает streamable-http как псевдоним для http. Спецификация MCP использует для этого транспорта имя streamable-http, поэтому конфигурации, скопированные из документации сервера, работают без изменений.

Запись JSON, в которой есть url, но нет type, является ошибкой конфигурации, потому что Claude Code считает запись без type stdio-сервером. Claude Code пропускает такой сервер и сообщает MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry.

Только приложение-хост SDK, например приложение на Agent SDK или настольное приложение, может зарегистрировать встроенный в процесс сервер "type": "sdk". Claude Code пропускает запись "type": "sdk" в .mcp.json, ~/.claude.json или настройках и сообщает Skipped — MCP server "<name>" declares type "sdk", which only an SDK host application can register.

[!NOTE]

При запусках с --output-format stream-json Claude Code также сообщает о пропущенной записи --mcp-config в поле mcp_server_errors события system/init, чтобы скрипты могли обнаружить, что сервер так и не загрузился.

Вариант 2: Добавление удалённого SSE-сервера

[!WARNING]

Транспорт SSE (Server-Sent Events) устарел. Используйте вместо него HTTP-серверы, где это возможно.

Некоторые сервисы по-прежнему предоставляют только SSE-эндпоинт. Добавляйте их той же командой claude mcp add --transport http <name> <url>, что и HTTP-сервер. Claude Code сначала пробует транспорт HTTP и переключается на SSE, если сервер его не принимает. Автоматическое переключение требует Claude Code v2.1.265 или новее.

В более ранней версии или для прямого подключения через SSE передайте вместо этого --transport sse:

# Базовый синтаксис
claude mcp add --transport sse <name> <url>

# Реальный пример: подключение к Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Пример с заголовком аутентификации
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

Вариант 3: Добавление локального stdio-сервера

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

Claude Code устанавливает в окружении запускаемого сервера переменную CLAUDE_PROJECT_DIR, указывающую на корень проекта, поэтому ваш сервер может разрешать пути относительно проекта, не завися от рабочего каталога. Это тот же каталог, который хуки получают в своей переменной CLAUDE_PROJECT_DIR. Читайте её внутри процесса вашего сервера, например process.env.CLAUDE_PROJECT_DIR в Node или os.environ["CLAUDE_PROJECT_DIR"] в Python.

CLAUDE_PROJECT_DIR — это стабильный корень проекта, и он не меняется, когда вы добавляете или удаляете рабочие каталоги во время сессии. Сервер, который ограничивает собственный доступ к файловой системе набором разрешённых каталогов, должен вместо этого реализовать MCP-запрос roots/list. Claude Code отвечает на roots/list каталогом запуска сессии плюс каждым дополнительным рабочим каталогом, который вы предоставили с помощью --add-dir, /add-dir или настройки additionalDirectories. Claude Code отправляет notifications/roots/list_changed, когда этот набор меняется.

Эта переменная устанавливается в окружении сервера, а не в собственном окружении Claude Code, поэтому ссылка на неё через подстановку ${VAR} в command или args записи .mcp.json с областью действия проекта или записи сервера с локальной или пользовательской областью действия в ~/.claude.json требует значения по умолчанию, например ${CLAUDE_PROJECT_DIR:-.}. Конфигурации MCP, предоставляемые плагинами, подставляют ${CLAUDE_PROJECT_DIR} напрямую и не нуждаются в значении по умолчанию.

# Базовый синтаксис
claude mcp add [options] <name> -- <command> [args...]

# Реальный пример: добавление сервера Airtable
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

[!NOTE]

Для stdio-серверов -- (двойной дефис) отделяет собственные опции Claude, такие как --transport, --env и --scope, от команды и аргументов, которые запускают сервер. Всё после -- передаётся серверу без изменений.

Например:

• claude mcp add --transport stdio myserver -- npx server → запускает npx server
• claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080 → запускает python server.py --port 8080 с KEY=value в окружении

Без -- Claude Code попытался бы разобрать флаги сервера, такие как --port выше, как свои собственные опции.

--env принимает несколько пар KEY=value. Если имя сервера идёт сразу после --env, CLI считает имя ещё одной парой и отклоняет его, поэтому поместите хотя бы одну другую опцию, например --transport stdio, между --env и именем сервера.

Как Claude Code останавливает stdio-сервер

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

• В macOS и Linux: Claude Code отправляет SIGINT, затем SIGTERM, если процесс всё ещё работает через 100 миллисекунд, затем SIGKILL ещё через 400 миллисекунд.
• В Windows: Claude Code закрывает stdin сервера, затем завершает дерево процессов сервера, если процесс всё ещё работает через 300 миллисекунд.

До версии v2.1.296 Claude Code в Windows сразу завершал дерево процессов сервера, не закрывая предварительно stdin и не дожидаясь завершения.

Вариант 4: Добавление удалённого WebSocket-сервера

WebSocket-серверы поддерживают постоянное двунаправленное соединение, что подходит для удалённых MCP-серверов, которые отправляют Claude события по собственной инициативе. Используйте вместо этого HTTP, если ваш сервер только отвечает на запросы, так как HTTP поддерживает OAuth и флаг claude mcp add --transport, а WebSocket не поддерживает ни то, ни другое.

Настраивайте WebSocket-серверы в .mcp.json или с помощью claude mcp add-json:

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

Запись type: "ws" принимает те же поля url, headers, headersHelper, timeout и alwaysLoad, что и http. Аутентификация выполняется только через заголовки, поэтому передайте статический токен в headers или генерируйте его при подключении с помощью headersHelper. Флаг claude mcp add --transport не принимает ws.

Добавление сервера по инструкциям по настройке, написанным для другого клиента

MCP-серверы не привязаны к Claude Code, поэтому инструкции по настройке сервера могут быть написаны для Claude Desktop, Cursor или другого MCP-клиента и не содержать команды claude mcp add. Чтобы всё равно добавить сервер, найдите в этих инструкциях URL, команду запуска или блок JSON:

• URL, например https://mcp.example.com/mcp: сервер удалённый.
• Команда запуска, например npx -y @example/mcp-server: сервер работает на вашей машине.
• Блок JSON mcpServers: конфигурация, написанная для файла настроек другого клиента.

Каждый из них — один из входных данных, которые принимают четыре варианта из раздела Установка MCP-серверов. Найдите ниже свой случай, чтобы превратить его в команду, которую принимает Claude Code. Каждая команда записывает конфигурацию в локальную область действия, если вы не добавите --scope project или --scope user.

Добавление сервера из URL

URL означает, что сервер удалённый. Для эндпоинта https:// добавьте его с --transport http или следуйте Варианту 2, если в инструкциях сказано, что эндпоинт использует SSE. Для эндпоинта wss:// используйте вместо этого Вариант 4, так как --transport не принимает ws:

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

Если в инструкциях также указан API-ключ или заголовок с токеном, передайте его с --header, как показано в Варианте 1.

Добавление сервера из команды npx, uvx или двоичного файла

Команда запуска означает, что сервер работает как локальный stdio-процесс. Поместите всю команду после --, чтобы Claude Code передал флаги, такие как -y, команде, запускающей сервер, а не считал их своими опциями. Передайте все переменные окружения, которые требуют инструкции, с помощью --env после имени сервера и перед --:

claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server

Вариант 3 подробно описывает разделитель --.

Добавление сервера из блока JSON mcpServers

Блок mcpServers, написанный для другого MCP-клиента, например Claude Desktop, использует тот же ключ-обёртку и ту же форму записи, которые читает Claude Code. Передайте claude mcp add-json объект внутри mcpServers, а не обёртку. Две разновидности записей требуют предварительного исправления:

• url без type: добавьте "type": "http", "type": "sse" или "type": "ws" в соответствии с эндпоинтом. Claude Code считает запись без type stdio-сервером, поэтому запись с url без type не работает.
• Ключ с символами, отличными от букв, цифр, дефисов и подчёркиваний: выберите имя сервера, в котором используются только эти символы. В остальных случаях ключ и есть имя сервера.

Например, этот блок:

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"]
    }
  }
}

превращается в эту команду:

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

Раздел Добавление MCP-серверов из конфигурации JSON описывает экранирование в оболочке и флаг --scope для add-json. Чтобы вместо этого поделиться сервером с вашей командой, добавьте --scope project или добавьте запись в mcpServers в файле .mcp.json в корне проекта и сделайте коммит. Раздел Область действия проекта описывает, как Claude Code загружает и одобряет этот файл.

Каждая команда claude mcp add и claude mcp add-json при успехе выводит строку Added .... Чтобы проверить, что Claude Code подключился, выполните claude mcp get <name>; раздел Статус сервера описывает показываемые статусы и шаг одобрения для серверов из .mcp.json.

Управление серверами

После настройки вы можете управлять своими MCP-серверами с помощью этих команд:

# Список всех настроенных серверов
claude mcp list

# Получить сведения о конкретном сервере
claude mcp get notion

# Удалить сервер
claude mcp remove notion

# (внутри Claude Code) Проверить статус сервера
/mcp

Когда вы удаляете удалённый сервер, Claude Code также удаляет токены OAuth и регистрацию клиента, которые он сохранил для этого сервера. Claude Code не отзывает токены на сервере авторизации, который их выдал. Чтобы отозвать токены там, где сервер авторизации поддерживает отзыв, выполните в оболочке claude mcp logout <name> перед claude mcp remove <name>.

Статус сервера

claude mcp add подтверждает успешное добавление, выводя строку Added ..., что означает, что конфигурация записана. Если вместо этого команда выводит сообщение was not saved, см. MCP server was not saved or removed; для сообщения may not have been saved см. MCP server may not have been saved or removed.

claude mcp list показывает рядом с каждым сервером в списке статус работоспособности, например ✔ Connected, ! Needs authentication или ✘ Failed to connect. Статус сбоя означает, что Claude Code не смог подключиться к этому серверу, а не то, что не удалось выполнить команду list.

Статусы из этого списка отражают решение конфигурации, а не попытку подключения, поэтому Claude Code выводит их без подключения к серверу:

• ⏸ Pending approval (run `claude` to approve): сервер с областью действия project из .mcp.json, который вы ещё не подтвердили. Claude Code показывает его и в claude mcp list, и в claude mcp get <name>. Запустите claude в интерактивном режиме, чтобы просмотреть и подтвердить его.
• ✘ Rejected (see disabledMcpjsonServers in settings): сервер из .mcp.json, который отклоняет запись disabledMcpjsonServers. Claude Code показывает его только в claude mcp get <name>.
• ⊘ Disabled for this project (re-enable via /mcp): сервер, указанный в списке disabledMcpServers проекта. Claude Code показывает его и в claude mcp list, и в claude mcp get <name>. Включите сервер обратно в панели /mcp.
• ✘ Blocked by enterprise managed policy: сервер, который отклоняет одна из политик вашей организации. Claude Code показывает его и в claude mcp list, и в claude mcp get <name>. Сервер, заблокированный списком разрешённых, списком запрещённых или другим ограничением в управляемой конфигурации MCP, скрыт в обеих командах, а не показан с этим статусом. Спросите администратора, какая политика блокирует сервер.

Одобрение серверов проекта и доверие к рабочему пространству

claude mcp list и claude mcp get читают одобрения .mcp.json только из файлов настроек, не добавленных в репозиторий, пока вы не доверитесь рабочему пространству, запустив в нём claude и приняв диалоговое окно доверия к рабочему пространству. Клонированный репозиторий не может одобрить собственные серверы: enableAllProjectMcpServers или enabledMcpjsonServers, добавленные в .claude/settings.json проекта, игнорируются в недоверенной папке, и сервер остаётся в статусе ⏸ Pending approval вместо подключения и проверки работоспособности.

Одобрения из этих источников по-прежнему применяются в недоверенной папке:

• ваш пользовательский ~/.claude/settings.json
• управляемые настройки
• настройки, переданные с --settings

Claude Code также применяет одобрения из неотслеживаемого .claude/settings.local.json, но для проверки того, отслеживается ли файл, он запускает git, а эту проверку он выполняет только в доверенной папке. В папке, которой вы никогда не доверяли, Claude Code ждёт диалогового окна доверия, прежде чем применить одобрения из файла, если только папка не является вашим собственным каталогом конфигурации: вашим домашним каталогом или каталогом, чей .claude вы указали в CLAUDE_CONFIG_DIR. До версии v2.1.207 Claude Code применял одобрения из неотслеживаемого .claude/settings.local.json даже в папке, которой вы никогда не доверяли.

Запись disabledMcpjsonServers в любом файле настроек по-прежнему отклоняет сервер.

Подробности статуса сервера

В /mcp, включая меню сервера там, и в менеджере /plugin удалённый HTTP- или SSE-сервер, который вы использовали раньше, может показывать статус cached, например cached 2h ago · connects on first use · 5 tools. Claude Code загрузил список инструментов сервера из своего кэша обнаружения, сохранённого в предыдущей сессии, вместо подключения при запуске, и Claude Code подключает сервер, когда Claude впервые вызывает один из инструментов этого сервера. Инструменты доступны с вашего первого сообщения, поэтому вам ничего не нужно делать. Кэш обнаружения и его статус cached требуют Claude Code v2.1.221 или новее.

Кэш обнаружения по умолчанию отключён, если постепенное развёртывание не включило его для вашей учётной записи. Установите MCP_DISCOVERY_CACHE=1, чтобы включить его, или 0, чтобы оставить его отключённым, даже если развёртывание его включило. До версии v2.1.238 кэш был включён по умолчанию.

Когда вы выбираете Disable или Clear authentication в меню сервера в /mcp, Claude Code также удаляет запись кэша этого сервера. Reconnect тоже удаляет её для подключённого сервера или сервера со сбоем; для сервера со статусом cached Reconnect подключает сервер сразу и сохраняет запись. В следующий раз, когда Claude Code подключится к серверу после удаления записи, он получит список инструментов с сервера, а не из кэша.

Сбои подключения и ненастроенные серверы

Когда статус сервера — ✘ Failed to connect, claude mcp list добавляет подробности сбоя к этой строке статуса, а claude mcp get <name> показывает их в строке Issue:. Подробности — это HTTP-статус или код ошибки, а также любой текст ошибки, возвращённый сервером. Подробное представление сервера в /mcp включает тот же текст от сервера в строке Issue:.

Claude Code удаляет из этих подробностей текст, похожий на учётные данные, и никогда не включает раскрытый URL сервера, который может содержать секреты. Claude Code не добавляет подробностей к статусу ✘ Connection error, потому что текст исключения, который он вывел бы там, может содержать этот URL.

Когда вы завершаете аутентификацию из /mcp, а подключение по-прежнему не удаётся с HTTP-статусом или кодом ошибки транспорта, Claude Code добавляет этот код и origin URL сервера в сообщение, которое выводит после попытки. Origin — это схема и хост, плюс порт, если он указан в URL, например https://mcp.example.com.

• Путь и строка запроса никогда не появляются в этом сообщении.
• Для сервера в локальной, проектной или пользовательской области действия или в управляемой конфигурации MCP origin показывает хост в том виде, в каком он записан в этой конфигурации, поэтому ссылка ${VAR} в хосте в сообщении не раскрывается.
• Для сбоя без статуса или кода ошибки Claude Code показывает текст ошибки без origin.

Удалённый сервер, в конфигурации которого указан пустой url, отображается как not configured в /mcp, в claude mcp list и в менеджере /plugin, и Claude Code не пытается к нему подключиться. Плагин может включать такую запись-заполнитель для коннектора, который вы настроите позже, поэтому Claude Code не сообщает о ней как об ошибке или проблеме настройки. В подробном представлении сервера в /mcp отображается No URL configured for this server; укажите url записи, чтобы подключить его.

Предупреждения о конфигурации

Claude Code предупреждает о перечисленных ниже проблемах конфигурации. В каждом пункте указано, что проверяет Claude Code и как устранить предупреждение:

• Скрытые пробельные символы: Claude Code предупреждает, когда значение конфигурации MCP содержит скрытые начальные или конечные пробельные символы, которые часто появляются при вставке токена с завершающим переводом строки. Claude Code проверяет command, url, каждую запись args, а также значения и имена ключей в env и headers. Claude Code показывает предупреждение в выводе claude mcp list и в /mcp, называя затронутые поля без вывода их значений, например Leading or trailing whitespace in: headers.Authorization. Claude Code не обрезает пробельные символы и использует значения точно в том виде, в каком они записаны, поэтому отредактируйте конфигурацию, чтобы их удалить.
• Одно имя в нескольких областях действия: если вы определяете одно и то же имя сервера в нескольких областях действия с разными эндпоинтами, Claude Code предупреждает о конфликте в выводе claude mcp list и в /mcp. Claude Code хранит входы через OAuth отдельно для каждого эндпоинта, поэтому, когда вы проходите аутентификацию для определения, загружаемого в одном проекте, вам всё равно нужно отдельно войти в проекте, где загружается другое определение. Оставьте нужный эндпоинт и удалите остальные с помощью claude mcp remove <name> --scope <scope>. В предупреждении Claude Code приводит эндпоинт каждой области действия в том виде, в каком он записан в вашей конфигурации, с нераскрытыми ссылками ${VAR}, поэтому он никогда не показывает разрешённое значение, такое как API-ключ.
• Зарезервированные имена: Claude Code резервирует имена своих встроенных серверов, включая workspace, claude-in-chrome, computer-use, Claude Preview и Claude Browser. Если ваша конфигурация определяет сервер с зарезервированным именем, Claude Code пропускает его при загрузке и показывает предупреждение с просьбой переименовать его. claude mcp add отклоняет зарезервированное имя с ошибкой. Claude Preview и Claude Browser обозначают встроенный сервер, который использует панель предпросмотра настольного приложения Claude Code.
• Отсутствующая переменная окружения: если ссылка ${VAR} в конфигурации сервера указывает на переменную, которая не установлена и не имеет :-default, Claude Code выводит предупреждение в claude mcp list и в /mcp, называя переменную, и всё равно загружает сервер с нераскрытым текстом ${VAR}. Установите переменную или добавьте резервный вариант ${VAR:-default}. В url и headers удалённого сервера некоторые переменные учётных данных вместо этого читаются как пустые, без предупреждения.

Доступность инструментов

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

Количество инструментов в облачной сессии

В облачной сессии значение вида 3 of 13 tools available означает, что Claude не может использовать остальные 10. Проверьте, среди прочего, следующие причины:

• Правило запрета в .claude/settings.json вашего репозитория называет этот инструмент или весь его сервер: удалите правило, если ваша сессия читает этот файл
• Полное имя инструмента длиннее 128 символов: выполните шаги для слишком длинного имени
• Сервер предоставляет инструмент для своего собственного интерфейса, а не для Claude: если вы поддерживаете сервер, добавьте model в _meta.ui.visibility инструмента, чтобы предоставить инструмент Claude. В противном случае исправлять нечего.

Инструменты сервера, который ещё подключается

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

• С поиском инструментов, по умолчанию: ожидание происходит внутри вызова ToolSearch.
• Без поиска инструментов: Claude вместо этого использует инструмент WaitForMcpServers. К конфигурациям без поиска инструментов относятся ENABLE_TOOL_SEARCH=false и модель, выпущенная раньше Claude Opus 4.5, Claude Sonnet 4.5 и Claude Haiku 4.5, на Agent Platform от Google Cloud. Для шлюза ANTHROPIC_BASE_URL см. Поиск инструментов через LLM-шлюз.
• В Microsoft Foundry при развёртывании, размещённом в Azure: Claude начинает с пути поиска инструментов, а не с WaitForMcpServers, так как Claude Code узнаёт об отклонении на стороне сервера развёртывания только из API. После того как Claude Code переключит это развёртывание на предварительную загрузку, инструменты сервера, завершившего подключение, становятся доступны при следующем запросе Claude.

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

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

Отключение сервера без его удаления

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

Когда вы переключаете сервер, Claude Code записывает ваш выбор для каждого проекта в ~/.claude.json, в один из двух списков, которые охватывают непересекающиеся наборы серверов:

• disabledMcpServers: список исключений для пользовательских серверов, серверов плагинов, серверов, которые ваша организация предоставляет через управляемые настройки, коннекторов claude.ai, которые Claude Code получает сам, и встроенных серверов, включённых по умолчанию. Claude Code не подключается к серверу, указанному здесь. Когда вы отключаете коннектор claude.ai с помощью переключателя /mcp для проекта, описанного в разделе Отключение коннекторов claude.ai, Claude Code записывает его в этот список под отображаемым именем, например claude.ai Slack.
• enabledMcpServers: список включения для встроенных серверов, отключённых по умолчанию, таких как computer-use. Claude Code подключается к серверу, отключённому по умолчанию, только если вы укажете его здесь.

Для каждого сервера Claude Code проверяет ровно один из двух списков, поэтому ни один список не переопределяет другой. Если вы добавите обычный сервер в enabledMcpServers или встроенный сервер, отключённый по умолчанию, в disabledMcpServers, Claude Code проигнорирует эту запись.

disabledMcpServers и enabledMcpServers не связаны с enabledMcpjsonServers и disabledMcpjsonServers, которые управляют одобрением серверов, определённых в файле .mcp.json проекта.

Среды выполнения MCP-клиента

Claude Code подключается к MCP-серверам через одну из двух сред выполнения клиента. Среда выполнения v1 построена на MCP TypeScript SDK 1.x. Среда выполнения v2 — это тот же код на MCP TypeScript SDK 2.0, который добавляет ревизию протокола MCP 2026-07-28. Остальная часть этой страницы относится к обеим средам выполнения, кроме разделов, где явно упомянута среда выполнения v2.

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

В сессиях, где он не получает флаги функций, Claude Code по умолчанию использует среду выполнения v2 в Claude Code v2.1.274 или новее:

• Сессии на Amazon Bedrock, Claude Platform on AWS, Agent Platform от Google Cloud или Microsoft Foundry, если платформа-хост, встраивающая Claude Code, не устанавливает CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST
• Сессии с входом через шлюз приложений Claude
• Сессии, в которых вы отключаете телеметрию или получение флагов функций, например с помощью DISABLE_TELEMETRY

В v2 Claude Code также:

• Спрашивает HTTP-, stdio-серверы и серверы коннекторов claude.ai, поддерживают ли они более новую ревизию, и использует её с теми, которые поддерживают. Это относится и к коннекторам облачных сессий и сессий Remote Control. Ко всем остальным серверам он подключается так же, как v1.
• Получает уведомления list_changed от серверов на более новой ревизии через поток, который держит открытым.
• Не регистрирует сервер канала, который подключается на более новой ревизии, потому что эта ревизия не может передавать сообщения канала.
• Прерывает вход через MCP OAuth, если ответ авторизации указывает неожиданного издателя.
• Отправляет учётные данные MCP OAuth только на эндпоинт токена, обслуживаемый по HTTPS или на localhost, 127.0.0.1 или ::1. Вход не удаётся для сервера, эндпоинт токена которого — простой http:// в любом другом месте, например на устройстве в вашей локальной сети. См. Refusing to send credentials to non-https token endpoint.

Anthropic может оставить конкретный сервер на более ранней версии протокола или без этого потока с помощью флага функции, который получает Claude Code. Чтобы выбрать среду выполнения самостоятельно, задайте MCP_SDK_GENERATION значение v1 или v2.

Чтобы решить, спрашивает ли Claude Code серверы о более новой ревизии, задайте MCP_PROTOCOL_NEGOTIATION значение auto или legacy. Если эта переменная не задана, Claude Code может не спрашивать stdio-сервер в течение 7 дней, например после того как сервер завершился в ответ на вопрос. Чтобы обновлённый сервер был опрошен раньше, задайте auto.

Динамическое обновление инструментов

MCP-сервер может изменять предлагаемые им инструменты, промпты или ресурсы во время подключения и отправлять уведомление list_changed. Когда такое уведомление приходит:

• В интерактивной сессии терминала Claude Code получает обновлённый список с этого сервера, поэтому вам не нужно его переподключать.
• В неинтерактивном режиме с флагом -p и в Agent SDK Claude Code при этих уведомлениях обновляет только список инструментов.

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

Потоки уведомлений в среде выполнения v2

В среде выполнения v2 Claude Code получает уведомления list_changed от сервера на более новой ревизии протокола через поток, который держит открытым. Когда поток закрывается, Claude Code открывает его снова с двумя ограничениями:

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

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

Автоматическое переподключение

Claude Code переподключает удалённый сервер, который отключился во время сессии, и повторяет попытку первого подключения HTTP- или SSE-сервера после временной ошибки. Для stdio-сервера см. Stdio-серверы, которые завершаются или не запускаются.

Отключения удалённого сервера во время сессии

Сначала Claude Code пытается переподключить отключившийся удалённый сервер до пяти раз с экспоненциальной задержкой, начиная с задержки в одну секунду и удваивая её каждый раз:

• В интерактивной сессии: /mcp показывает сервер как ожидающий, пока Claude Code переподключается. После пяти неудачных попыток Claude Code помечает сервер как сбойный или как требующий аутентификации, если серверу снова нужна авторизация. Когда он помечает сервер как сбойный, вы видите уведомление MCP server "<name>" disconnected · open /mcp to reconnect. Вы можете повторить попытку вручную в /mcp.
• В запусках claude -p и сессиях Agent SDK: Claude Code делает те же пять попыток, без панели /mcp для их отображения. Если все пять неудачны, запуск продолжается без инструментов сервера:
  • После временной ошибки, такой как ответ 5xx или таймаут: Claude Code продолжает повторять попытки для HTTP- или SSE-сервера в фоне. Повторные попытки продолжаются примерно до получаса, и инструменты сервера снова становятся доступны, когда одна из них подключается. До тех пор сессия Agent SDK сообщает статус failed, и ваш код может переподключить сервер. Чтобы переподключить его в claude -p, запустите его заново.
  • Когда сервер требует повторного входа: Claude Code прекращает повторные попытки, а сессия Agent SDK сообщает статус сервера needs-auth. Войдите с помощью claude mcp login <name> в своей оболочке. Затем запустите его заново или, в сессии Agent SDK, вместо этого переподключите сервер.

Неудачные первые подключения

Когда первое подключение HTTP- или SSE-сервера не удаётся из-за временной ошибки, такой как ответ 5xx, отказ в соединении или таймаут, Claude Code повторяет попытку до трёх раз. Если подключение по-прежнему не удаётся, Claude Code помечает сервер как сбойный.

Эти повторные попытки не применяются в следующих случаях:

• Первое подключение stdio-сервера. Чтобы попробовать снова, см. Stdio-серверы, которые завершаются или не запускаются
• Первое подключение WebSocket-сервера. Чтобы попробовать снова в интерактивной сессии в терминале, выберите Reconnect в меню сервера в /mcp
• Ошибка аутентификации или «не найдено», потому что для её устранения требуется изменить конфигурацию. Когда headersHelper — единственный источник заголовка Authorization для сервера, Claude Code всё равно повторяет попытку при ошибке аутентификации, потому что перезапускает helper при каждой попытке и может получить свежие учётные данные

Stdio-серверы, которые завершаются или не запускаются

Чтобы снова запустить stdio-сервер, смотрите столбец, соответствующий тому, что с ним произошло. Найдите свою строку по тому, как вы запускаете Claude Code: интерактивная сессия, запуск claude -p или сессия Agent SDK.

Неудачные запросы обнаружения

После подключения сервера Claude Code отправляет ему запросы обнаружения возможностей, такие как tools/list, prompts/list и resources/list. Claude Code повторяет эти запросы до трёх раз с короткой задержкой после временной сетевой или серверной ошибки. Он не повторяет попытки при ошибках аутентификации, ответах 4xx или таймаутах запросов.

Самостоятельная повторная попытка для сбойных серверов

Чтобы повторить попытку для всех серверов, которые дали сбой или требуют аутентификации, выполните /mcp reconnect all в промпте Claude Code в интерактивной сессии в терминале. Для этого требуется Claude Code v2.1.284 или новее. Более ранние версии выводят MCP server "all" not found.

Как Claude узнаёт о сбое сервера

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

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

Отправка сообщений через каналы

MCP-сервер также может отправлять сообщения прямо в вашу сессию, чтобы Claude мог реагировать на внешние события, такие как результаты CI, оповещения мониторинга или сообщения чата. Чтобы включить это, ваш сервер объявляет возможность claude/channel, а вы включаете его флагом --channels при запуске. См. Каналы, чтобы использовать официально поддерживаемый канал, или Справочник по каналам, чтобы создать собственный.

В среде выполнения v2 сервер канала, который согласует ревизию протокола MCP 2026-07-28, не может доставлять сообщения канала, поэтому Claude Code не регистрирует его как канал. Сервер канала, который не поддерживает эту ревизию, подключается по более раннему рукопожатию и регистрируется как прежде.

Claude Code по умолчанию запрашивает эту ревизию у stdio-серверов. Чтобы оставить stdio-сервер канала на более раннем рукопожатии, установите MCP_PROTOCOL_NEGOTIATION в legacy, что оставляет на нём все серверы.

[!TIP]

Советы:

• Используйте флаг -s или --scope, чтобы указать, где хранится конфигурация:
  • local (по умолчанию): доступно только вам в текущем проекте
  • project: доступно всем в проекте через файл .mcp.json
  • user: доступно вам во всех проектах
• Устанавливайте переменные окружения с помощью флагов -e или --env (например, -e KEY=value)
• Флаги --transport и --header также принимают короткие формы -t и -H
• Настройте таймаут запуска MCP-сервера с помощью переменной окружения MCP_TIMEOUT (например, MCP_TIMEOUT=10000 claude устанавливает таймаут в 10 секунд)
• Задайте таймаут выполнения инструментов для отдельного сервера, добавив поле timeout в миллисекундах в запись .mcp.json этого сервера, например "timeout": 600000 для десяти минут. Это переопределяет переменную окружения MCP_TOOL_TIMEOUT только для этого сервера
• Claude Code показывает предупреждение, когда вывод инструмента MCP превышает 10 000 токенов, и по умолчанию ограничивает вывод 25 000 токенами. Чтобы изменить лимит токенов, установите переменную окружения MAX_MCP_OUTPUT_TOKENS, например MAX_MCP_OUTPUT_TOKENS=50000. Порог предупреждения фиксирован. Если сервер не повышает собственный лимит инструмента, успешные текстовые результаты длиннее 50 000 символов сохраняются в файл независимо от этой переменной. См. Ограничения и предупреждения вывода MCP
• Используйте /mcp для аутентификации на удалённых серверах, требующих аутентификации OAuth 2.0

Ограничения времени для вызовов MCP-инструментов

Чтобы ограничить время выполнения вызова MCP-инструмента:

• Для отдельного сервера: добавьте поле timeout в миллисекундах в запись конфигурации этого сервера
• Для всех серверов: установите MCP_TOOL_TIMEOUT

timeout отдельного сервера — это жёсткий лимит реального времени на каждый вызов инструмента, и уведомления о прогрессе от сервера его не продлевают. Значения меньше 1000 игнорируются, и используется MCP_TOOL_TIMEOUT или его значение по умолчанию около 28 часов, если эта переменная не установлена. Для HTTP-, SSE-сервера или сервера коннектора claude.ai также есть второй таймер на каждый запрос, который охватывает каждый запрос вплоть до первого байта ответа сервера. Claude Code устанавливает этот таймер в наибольшее из трёх значений: 60 секунд, таймаут инструментов, применяемый к серверу, и MCP_TIMEOUT. Значение по умолчанию 28 часов для неустановленного MCP_TOOL_TIMEOUT в этом сравнении не участвует, а значение меньше 60 секунд не сокращает таймер. У stdio- и WebSocket-серверов нет таймера на каждый запрос.

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

Вызов инструмента MCP-сервера, который в течение окна бездействия не отправляет ни ответа, ни уведомления о прогрессе, прерывается с ошибкой, не дожидаясь лимита реального времени. Таймаут бездействия применяется ко всем типам серверов, кроме серверов IDE и встроенных в процесс серверов SDK. Окно бездействия по умолчанию составляет пять минут для HTTP-, SSE-, WebSocket-серверов и серверов коннекторов claude.ai и 30 минут для stdio-серверов.

Установите переменную окружения CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT в миллисекундах, чтобы изменить окно бездействия, или установите её в 0, чтобы отключить проверку.

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

Автоматический перевод долгих вызовов инструментов в фон

Если подробный вид фонового вызова в /tasks показывает runs on the server; survives exiting this session, см. MCP-задачи, выполняемые на сервере.

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

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

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

Чтобы изменить или отключить автоматический перевод в фон:

• Установите переменную окружения CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS в миллисекундах, чтобы изменить порог, или в 0, чтобы отключить автоматический перевод в фон. При 0 Claude также ждёт MCP-задачи в интерактивной сессии
• Задайте CLAUDE_CODE_DISABLE_BACKGROUND_TASKS равной 1, чтобы отключить автоматический перевод в фон и фоновые команды

Некоторые вызовы никогда не переводятся в фон:

• Вызовы из субагентов; Claude Code переводит в фон только вызовы основного диалога
• Вызовы к серверам IDE
• Вызовы в неинтерактивном режиме, если только CLAUDE_AUTO_BACKGROUND_TASKS не установлена в 1, так как однократный запуск может завершиться до получения результата

Вызов, ожидающий открытого диалогового окна elicitation, не переводится в фон, пока окно открыто; сервер ждёт вашего ввода, а не работает медленно, поэтому Claude Code откладывает перевод до закрытия диалогового окна.

MCP-задачи, выполняемые на сервере

MCP-задача — это длительная работа, например экспорт отчёта или сборка, которую MCP-сервер выполняет сам с помощью расширения MCP tasks. Вызов инструмента Claude возвращается, как только сервер принимает работу, поэтому Claude продолжает работать, если только вы не заставите Claude ждать. Когда работа завершается, об этом сообщается в транскрипте, и Claude получает результат. Попросите Claude показать его.

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

[!NOTE]

MCP-задачи доступны в публичной бета-версии в Claude Code CLI и требуют Claude Code v2.1.304 или новее. В разделе Что нужно, чтобы вызов стал MCP-задачей перечислены сессии и серверы, которые их получают.

Остановка MCP-задачи или получение её результата

Чтобы остановить выполняющуюся задачу, выберите её в /tasks и нажмите x или попросите об этом Claude. Claude Code прекращает отслеживать задачу и просит сервер отменить её, хотя сервер всё равно может её завершить. Сначала переподключите отключённый сервер из /mcp, иначе запрос на отмену не будет отправлен, а Claude Code забудет задачу и не сможет снова её отслеживать. Нажатие Esc не останавливает фоновую задачу.

Когда задача завершается, в транскрипте появляется строка вроде этой:

MCP task <server task id> (<server>/<tool>) completed.

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

Ответ на вопрос от MCP-задачи

Выполняющаяся задача может открыть диалоговое окно elicitation, чтобы запросить у вас ввод. Пока открыт /tasks, диалоговое окно скрыто, поэтому закройте /tasks, чтобы ответить. Отказ или нажатие Esc — это ответ серверу, который затем решает, продолжается ли задача.

В неинтерактивной сессии Claude Code просит сервер отменить задачу, которая запрашивает ввод, не запуская ваши хуки Elicitation и не вызывая коллбэк onElicitation из Agent SDK.

Выход, очистка или возобновление во время выполнения MCP-задачи

Задача на удалённом сервере продолжает выполняться после вашего выхода. Процесс stdio-сервера останавливается при выходе из Claude Code, хотя его задачи показывают runs on the server; survives exiting this session в /tasks. Если в документации этого сервера не сказано, что работа переживает процесс, сначала дайте этим задачам завершиться или остановите их в /tasks.

Что нужно, чтобы вызов стал MCP-задачей

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

• Сервер поддерживает задачи
• Сервер является HTTP-сервером, stdio-сервером или сервером коннектора claude.ai, подключённым по ревизии протокола 2026-07-28. Установка MCP_SDK_GENERATION=v1 или MCP_PROTOCOL_NEGOTIATION=legacy это исключает
• Сессия получает флаги функций, то есть не у стороннего провайдера, такого как Amazon Bedrock, и не с отключённой телеметрией или получением флагов
• Anthropic включила MCP-задачи для вашего типа сессии. В v2.1.304 или новее это охватывает сессии CLI в терминале, сессии Agent SDK и запуски GitHub Actions. В других интерфейсах, например расширении VS Code и десктопном приложении, MCP-задач нет
• Вызов исходит из основного диалога, а не из субагента
• Либо сессия интерактивная, либо в сессии Agent SDK или в запуске claude -p, читающем --input-format stream-json:
  • CLAUDE_AUTO_BACKGROUND_TASKS равна 1
  • CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND не равна 1
  • CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS не равна 0

Любой другой вызов — это обычный вызов инструмента, и в разделе Автоматический перевод длительных вызовов инструментов в фон сказано, какие из них переносятся в фон.

Держите ввод сессии Agent SDK или stream-json открытым, потому что после закрытия ввода запуск не ждёт MCP-задачи. Однократный запуск claude -p "<prompt>" не получает MCP-задач.

Сообщения о статусе MCP-задачи

Эти сообщения в записи задачи в /tasks или в её завершающей строке в транскрипте означают, что Claude Code не может связаться с сервером или задачей. Пока одно из них отображается в /tasks, работа может по-прежнему выполняться: Claude Code её не трогает и продолжает проверять. Сообщения с 300s и сообщения о конфигурации остаются в записи даже после восстановления связи.

Ограничения времени для MCP-задач

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

Как заставить Claude ждать результата MCP-задачи

Чтобы Claude ждал результата задачи в интерактивной сессии, установите одну из двух переменных окружения, например в блоке env файла settings.json:

• CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS со значением 0: Claude ждёт завершения каждого вызова MCP-инструмента
• CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND со значением 1: Claude ждёт результата задачи. Пока включён автоматический перевод в фон, он по умолчанию переносит вызов через две минуты, поэтому короткие задачи завершаются на месте, а длинные вас не блокируют. Перенесённый вызов — это обычный фоновый вызов, а не MCP-задача. Он не переживает выход из сессии

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

Если вы установите CLAUDE_CODE_DISABLE_BACKGROUND_TASKS в 1 или запустите режим bare, само по себе это не заставит Claude ждать MCP-задачи. В этом примере CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS установлена в 0, поэтому Claude ждёт каждый вызов MCP-инструмента:

{
  "env": {
    "CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS": "0"
  }
}

MCP-задачи для авторов серверов

Если вы создаёте MCP-сервер, вы можете ответить на длительный tools/call задачей. Расширение MCP tasks определяет сообщения, которые вы отправляете. При подключении по ревизии протокола 2026-07-28 каждый запрос несёт клиентские возможности Claude Code в params._meta["io.modelcontextprotocol/clientCapabilities"], с "io.modelcontextprotocol/tasks": {} в extensions. Запрос tools/call, который не может стать задачей, не содержит этого расширения.

Ответ на вызов задачей

Отвечайте задачей, только когда запрос содержит расширение, иначе вызов завершится ошибкой инструмента Unsupported result type 'task' for tools/call. Вызов завершается так же, если в вашем ответе нет taskId или допустимого status. Объект задачи — это JSON-RPC result вашего ответа на tools/call, ему не нужен массив content, и здесь он включает необязательные statusMessage и pollIntervalMs:

{
  "resultType": "task",
  "taskId": "build-7f3a9c2e",
  "status": "working",
  "statusMessage": "Compiling, 40 of 212 files done",
  "createdAt": "2026-10-22T14:03:07Z",
  "lastUpdatedAt": "2026-10-22T14:03:07Z",
  "ttlMs": null,
  "pollIntervalMs": 5000
}

Claude Code принимает ответ-задачу без createdAt, lastUpdatedAt или ttlMs либо с pollIntervalMs, равным null. До v2.1.317 вызов вместо этого завершался ошибкой Unsupported result type. Чтобы работать и с этими версиями, отправляйте три поля, которые требует расширение tasks, а pollIntervalMs отправляйте числом или не отправляйте вовсе.

На HTTP-сервере или сервере коннектора claude.ai ответ задачей должен начаться в пределах таймера для отдельного запроса, поэтому сначала примите работу и ответьте, а затем выполняйте её.

Сообщение о статусе, результатах и вопросах

Сразу после ответа задачей Claude Code отправляет tasks/get с { "taskId": ... }, затем повторяет его раз в интервал опроса. Расширение tasks требует, чтобы ваш ответ содержал "resultType": "complete" вместе с taskId, status, createdAt, lastUpdatedAt и ttlMs. ttlMs может быть null, а statusMessage и pollIntervalMs необязательны. В этом примере сообщается о завершении сборки:

{
  "resultType": "complete",
  "taskId": "build-7f3a9c2e",
  "status": "completed",
  "createdAt": "2026-10-22T14:03:07Z",
  "lastUpdatedAt": "2026-10-22T14:09:41Z",
  "ttlMs": null,
  "result": {
    "content": [{ "type": "text", "text": "Build succeeded: 212 files, 0 warnings" }]
  }
}

MCP-серверы, предоставляемые плагинами

Плагины могут включать MCP-серверы, которые предоставляют инструменты и интеграции при включении плагина.

Как работают MCP-серверы плагинов:

• Плагины определяют MCP-серверы в .mcp.json в корне плагина или встроенно в plugin.json
• Когда вы включаете плагин, Claude Code автоматически запускает его MCP-серверы
• Claude Code предлагает инструменты MCP плагинов наряду с вручную настроенными инструментами MCP
• Вы добавляете и удаляете серверы плагинов, устанавливая или удаляя плагин, а не с помощью команд /mcp. Вы по-прежнему можете выключить сервер установленного плагина в /mcp, после чего Claude Code перестанет к нему подключаться без удаления плагина

Пример конфигурации MCP плагина:

В .mcp.json в корне плагина:

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

Или встроенно в plugin.json:

{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

Возможности MCP плагинов:

• Автоматический жизненный цикл: серверы подключаются и отключаются в следующие моменты:
  • При запуске сессии Claude Code автоматически подключает серверы включённых плагинов. В /mcp удалённый (HTTP или SSE) сервер плагина, который вы использовали раньше, может вместо этого показывать статус cached; Claude Code подключает его, когда Claude впервые вызывает один из его инструментов. Если подключение stdio-сервера плагина не удалось менее 15 минут назад, Claude Code пропускает подключение
  • Если вы включаете или отключаете плагин во время сессии, Claude Code подключает или отключает его MCP-серверы, когда изменение применяется. Раздел Применение изменений плагинов без перезапуска описывает, когда это происходит. В сессии без интерактивного терминала /reload-plugins не подключает и не отключает MCP-серверы плагинов; эти изменения вступают в силу в следующей сессии
  • При перезагрузке Claude Code сохраняет активные соединения серверов плагинов, конфигурация которых не изменилась, и делает то же самое, когда вы заменяете список MCP-серверов сессии из Agent SDK, не указывая их
  • Когда вы перемещаете сессию с помощью /cd в v2.1.246 или новее, Claude Code подключает серверы плагинов, которые включены настройками нового каталога, и отключает серверы плагинов, которые больше не включены, поэтому вам не нужно запускать /reload-plugins после перемещения
  • В облачных сессиях вызов MCP к серверу плагина, который ещё не подключён, например сразу после пробуждения неактивной сессии, запускает сервер по требованию и ждёт его подключения
• Заполнители путей: ${CLAUDE_PLUGIN_ROOT} разрешается в каталог установки плагина, ${CLAUDE_PLUGIN_DATA} — в каталог его постоянного состояния, а ${CLAUDE_PROJECT_DIR} — в стабильный корень проекта. Подстановка применяется к:
  • серверам stdio: command, args, env
  • серверам http, sse и ws: url, headers и headersHelper
• Доступ к пользовательскому окружению: доступ к тем же переменным окружения, что и у вручную настроенных серверов
• Несколько типов транспорта: поддержка транспортов stdio, SSE, HTTP и WebSocket, хотя поддержка транспортов может различаться в зависимости от сервера

Серверы плагинов отображаются в /mcp с индикаторами, показывающими, что они получены из плагинов.

claude mcp get скрывает значения, настроенные для stdio- или WebSocket-сервера плагина, потому что они могут содержать учётные данные:

• stdio-сервер: команда выводит Command: stdio, пустую строку Args: и каждую переменную окружения в виде NAME=[REDACTED]
• WebSocket-сервер: команда выводит URL: ws и каждый заголовок в виде <name>: [REDACTED], а claude mcp list показывает ws вместо URL

Чтобы увидеть, что настроил плагин, найдите плагин на диске и прочитайте его .mcp.json или plugin.json.

Имена инструментов MCP плагинов:

Инструменты MCP-сервера, входящего в состав плагина, содержат в своём вызываемом имени и имя плагина, и ключ сервера. Полная форма — mcp__plugin_<plugin-name>_<server-name>__<tool-name>, где любой символ вне A-Z, a-z, 0-9, _ и - заменяется на _. Для сервера database-tools из плагина с именем my-plugin инструмент query вызывается как:

mcp__plugin_my-plugin_database-tools__query

Используйте это полное имя при указании инструмента в правилах разрешений, списке allowed-tools скилла, поле tools субагента или matcher хука. Matcher хука, написанный для голого ключа сервера, например mcp__database-tools__.*, никогда не срабатывает для сервера, входящего в состав плагина.

Сам сервер регистрируется под именем с областью действия plugin:<plugin-name>:<server-name>, например plugin:my-plugin:database-tools. Используйте это имя там, где ожидается имя настроенного сервера, например в поле server хука mcp_tool.

Подробнее о включении MCP-серверов в плагины см. в справочнике по компонентам плагинов.

Области действия установки MCP

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

Локальная область действия

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

[!NOTE]

Термин «локальная область действия» для MCP-серверов отличается от общих локальных настроек. MCP-серверы с локальной областью действия хранятся в ~/.claude.json (в вашем домашнем каталоге), тогда как общие локальные настройки используют .claude/settings.local.json (в каталоге проекта). Подробнее о расположении файлов настроек см. в разделе Настройки.

# Add a local-scoped server (default)
claude mcp add --transport http stripe https://mcp.stripe.com

# Explicitly specify local scope
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

Команда записывает сервер в запись для вашего текущего проекта внутри ~/.claude.json. В примере ниже показан результат при запуске из /path/to/your/project:

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

Область действия проекта

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

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

Итоговый файл .mcp.json имеет стандартизированный формат:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

В целях безопасности в интерактивных сессиях Claude Code запрашивает подтверждение перед использованием серверов с областью действия проекта из файлов .mcp.json. Чтобы сбросить сделанные выборы подтверждения, выполните claude mcp reset-project-choices.

При запусках claude -p, в сессиях Agent SDK и в облачных сессиях вне потоков проекта Claude Code не может показать этот запрос: он загружает серверы с областью действия проекта без вопросов. Claude Code также пропускает запрос в сессии, которую вы запускаете в режиме bypassPermissions, если в ваших пользовательских настройках или в управляемых настройках задан параметр skipDangerousModePermissionPrompt. Чтобы всё же исключить сервер:

• Добавьте его в disabledMcpjsonServers, что блокирует его в любом режиме разрешений.
• Полностью исключите настройки проекта с помощью --setting-sources или опции SDK settingSources.
• Запустите сессию с флагом --strict-mcp-config. Тогда Claude Code использует только MCP-серверы, переданные через --mcp-config. Пропуск запроса подтверждения для серверов с областью действия проекта, которые Claude Code не загружает, требует Claude Code v2.1.246 или более поздней версии; до v2.1.246 строгая сессия всё равно ожидала подтверждения для них, из-за чего фоновые сессии зависали при запуске. О том, что делает этот флаг при наличии управляемого файла MCP, см. в разделе Эксклюзивный контроль с помощью managed-mcp.json.

В разделе Подтверждения серверов проекта и доверие к рабочему пространству описано, как подтверждения, закоммиченные в репозиторий, взаимодействуют с доверием к рабочему пространству.

Пользовательская область действия

Серверы с пользовательской областью действия хранятся в ~/.claude.json и доступны во всех проектах: они работают во всех проектах на вашем компьютере, оставаясь при этом доступными только вашей учётной записи. Эта область действия хорошо подходит для личных служебных серверов, инструментов разработки или сервисов, которые вы часто используете в разных проектах.

# Add a user server
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Иерархия и приоритет областей действия

Если один и тот же сервер определён в нескольких местах, Claude Code подключается к нему один раз, используя определение из источника с наивысшим приоритетом. Используется вся запись сервера из этого источника; поля между областями действия не объединяются.

1. Локальная область действия
2. Область действия проекта
3. Пользовательская область действия
4. Серверы, предоставляемые плагинами
5. Коннекторы claude.ai

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

Два написания URL считаются одним и тем же эндпоинтом, если они различаются только регистром букв в схеме или хосте, портом схемы по умолчанию, например :443 для https, или завершающей косой чертой. Другой путь, строка запроса, userinfo или нестандартный порт дают два разных сервера.

Сервер, который ваша организация предоставляет через управляемую настройку managedMcpServers, имеет приоритет над всеми перечисленными, поэтому если один из них его дублирует, Claude Code подключает определение организации. Требуется Claude Code v2.1.259 или более поздней версии.

Если вы открываете локальную сессию на вкладке Code в приложении Desktop, а stdio-сервер с одинаковым именем есть на верхнем уровне ~/.claude.json (пользовательская область действия) и в .mcp.json, вкладка Code использует определение из ~/.claude.json.

Подстановка переменных окружения в .mcp.json

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

Вы можете ссылаться на переменную окружения в значении command, args, env, url или headers сервера в одной из двух форм:

• ${VAR}: подставляет значение переменной окружения VAR
• ${VAR:-default}: подставляет значение VAR, если VAR задана, или default, если она не задана

Пример с подстановкой переменных

В этой записи сервера URL — это значение API_BASE_URL, за которым следует /mcp, со значением по умолчанию https://api.example.com, а API-ключ берётся из API_KEY:

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

Незаданные переменные без значения по умолчанию

Если переменная окружения, на которую есть ссылка, не задана и не имеет значения по умолчанию, конфигурация всё равно загружается: Claude Code выводит предупреждение об отсутствующей переменной для этого сервера в выводе claude mcp list и использует неподставленный текст ${VAR} как есть. Задайте переменную или добавьте резервный вариант :-default, чтобы сервер запускался с нужным вам значением. В url и headers удалённого сервера некоторые переменные с учётными данными вместо этого читаются как пустые, без предупреждения.

Переменные, заданные как пустая строка

Если вы задаёте переменной значение пустой строки, она считается заданной, поэтому ссылка ${VAR:-default} подставляется как пустая строка, а не как default. Для примера сервера, если вы зададите API_BASE_URL пустую строку, его url станет /mcp, а claude mcp list сообщит 'url' is not a valid URL. Чтобы использовать значение по умолчанию, удалите переменную, а не задавайте ей пустую строку.

Переменные с учётными данными, которые читаются как пустые

В url и headers удалённого сервера Claude Code читает переменные с учётными данными из вашего окружения как пустые, а не подставляет их. Это не позволяет файлу .mcp.json проекта или плагину отправить ваши учётные данные Claude Code или облачного провайдера на указанный в них сервер. Если вы напишете Bearer ${ANTHROPIC_AUTH_TOKEN}, сервер получит Bearer без учётных данных и отклонит запрос, обычно с кодом 401. Claude Code сообщит об этом как о неудачном подключении.

Охватываемые имена:

• Собственные учётные данные Claude Code, такие как ANTHROPIC_API_KEY и ANTHROPIC_AUTH_TOKEN
• Учётные данные вашего облачного провайдера, такие как AWS_BEARER_TOKEN_BEDROCK
• Другие учётные данные в вашем окружении, такие как HTTPS_PROXY и NPM_TOKEN

Охватываемое имя читается как пустое независимо от того, задали ли вы переменную, а резервный вариант :-default для него игнорируется. Базовый URL провайдера, такой как ANTHROPIC_BASE_URL, по-прежнему подставляется, поэтому "url": "${ANTHROPIC_BASE_URL}/mcp" работает, если только само значение URL не содержит учётные данные, например имя пользователя и пароль.

Имя вне этого набора, например API_KEY, подставляется как написано. Чтобы передать серверу одни из охватываемых учётных данных, скопируйте их в переменную с собственным именем и ссылайтесь на это имя.

Когда url или headers удалённого сервера ссылается на заданную вами охватываемую переменную, Claude Code указывает её имя в строке отладочного лога. Чтобы прочитать эту строку, выполните claude --debug-file /tmp/claude-debug.log и найдите в этом файле never expanded toward a remote server.

Как ссылки отображаются в /mcp и выводе CLI

Для сервера в локальной, проектной или пользовательской области действия следующие интерфейсы показывают ссылку ${VAR} по имени, а не как её разрешённое значение:

• URL или командная строка в подробном представлении сервера в /mcp
• Вывод claude mcp list и claude mcp get

Подробное представление /mcp показывает ссылки таким образом в Claude Code v2.1.268 или более поздней версии.

Для сервера, который ваша организация предоставляет через настройку managedMcpServers, эти интерфейсы показывают только хост URL.

Чтобы узнать, что показывают claude mcp list, claude mcp get и /mcp при сбое подключения, см. раздел Подробности состояния сервера.

Практические примеры

Пример: подключение к GitHub для проверки кода

GitHub's remote MCP server аутентифицируется с помощью токена личного доступа GitHub, переданного как заголовок. Чтобы получить его, откройте параметры токена GitHub, создайте новый детальный токен с доступом к репозиториям, с которыми вы хотите, чтобы Claude работал, затем добавьте сервер:

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

Замените YOUR_GITHUB_PAT на ваш токен личного доступа. Команда claude mcp add сохраняет конфигурацию без проверки учётных данных, поэтому здесь принимается значение-заполнитель, но позже сервер не сможет подключиться. Чтобы проверить соединение, запустите /mcp и убедитесь, что в строке сервера отображается галочка. Для сервера с неправильными учётными данными вместо неё отображается ✘, а сведения о сбое включают HTTP-статус, возвращённый сервером, например 401.

Затем работайте с GitHub:

Проверьте PR #456 и предложите улучшения

Создайте новую проблему для найденной нами ошибки

Покажите мне все открытые PR, назначенные мне

Пример: запрос к базе данных PostgreSQL

DBHub, пакет @bytebase/dbhub, — это MCP сервер, который подключает Claude к реляционной базе данных через строку подключения, которую вы передаете в --dsn. Используйте пользователя базы данных только для чтения в строке подключения, чтобы запросы, которые запускает Claude, не могли изменять данные:

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

Чтобы убедиться, что сервер запускается, запустите /mcp и проверьте, что в строке db отображается галочка.

Затем запрашивайте вашу базу данных естественным образом:

Какой у нас общий доход в этом месяце?

Покажите мне схему для таблицы orders

Найдите клиентов, которые не совершали покупку в течение 90 дней

Аутентификация с удалёнными MCP-серверами

Многие облачные MCP-серверы требуют аутентификации. Claude Code поддерживает OAuth 2.0 для безопасных соединений.

Claude Code помечает удалённый сервер как требующий аутентификации, когда сервер отвечает с 401 Unauthorized или 403 Forbidden. То, что показывает Claude Code, зависит от сервера:

• Для сервера, на который вы ещё не вошли, любой из этих кодов состояния помечает его в /mcp, чтобы вы могли завершить поток OAuth.
• Для коннектора claude.ai 401, вызванный отклонением claude.ai вашего токена сессии, не помечает коннектор, потому что повторная авторизация коннектора не может исправить ваш вход. Claude Code вместо этого показывает состояние отклонения токена сессии.
• Для сервера, чей заголовок Authorization вы настроили в headers или через headersHelper, 401 или 403 при подключении не помечает сервер, потому что исправлять нужно те учётные данные, которые вы настроили. Claude Code вместо этого сообщает о неудачном подключении. Если вы установили этот заголовок из ссылки ${VAR}, проверьте, является ли эта переменная одной из тех, которые Claude Code читает как пустые.
• Для коннектора, доставленного в облачную сессию, Claude Code не запускает поток входа, потому что прокси сессии аутентифицируется на коннекторе с авторизацией, которую вы предоставили в claude.ai. Когда коннектор там требует повторной авторизации, переподключите его на claude.ai/customize/connectors, а не из сессии.

Когда OAuth-сервер, на который вы уже вошли, отклоняет ваш сохранённый токен с 401 Unauthorized, Claude Code переподключается с новым токеном или без него:

• В вашем сохранённом входе есть токен обновления: Claude Code обновляет токен, переподключается и повторяет запрос один раз. Сервер помечается в /mcp, только если эта повторная попытка также не удаётся.
• В вашем сохранённом входе нет токена обновления: Claude Code подключается один раз без токена. Если сервер отвечает, его инструменты работают, пока вы не вошли в систему, а отклонённый токен удаляется. Если сервер отклоняет и это подключение, /mcp показывает, что сервер требует аутентификации.

При запуске claude -p или Agent SDK на macOS запрос, который Claude Code отправил, когда не мог прочитать ваш сохранённый токен, завершается ошибкой сохранённых учётных данных.

Когда сервер отклоняет сохранённый токен обновления, Claude Code немедленно показывает уведомление, указывающее на /mcp. Откройте /mcp и выберите Re-authenticate на сервере, чтобы войти снова до того, как следующий вызов инструмента завершится ошибкой.

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

Claude Code также показывает уведомление при запуске, когда один или несколько настроенных серверов требуют аутентификации, поэтому вам не нужно открывать /mcp, чтобы узнать, какие серверы требуют входа. Уведомление учитывает только серверы, на которые вы можете войти из Claude Code. До v2.1.218 оно также учитывало коннекторы claude.ai, которые не были подключены в claude.ai и которые можно подключить только из настроек claude.ai.

Уведомление объявляет каждый сервер один раз и исключает его из подсчёта при последующих запусках, пока этот сервер не подключится и снова не потребует входа. /mcp по-прежнему перечисляет каждый сервер, который требует входа.

У запуска claude -p или Agent SDK нет панели /mcp, поэтому Claude Code не может запустить там поток OAuth. Чтобы использовать сервер, требующий аутентификации, сначала завершите вход из интерактивной сессии: выполните /mcp в сессии или claude mcp login <name> в вашей оболочке. Когда настроенный сервер требует аутентификации во время запуска claude -p или Agent SDK с включённым поиском инструментов, Claude Code сообщает Claude, что инструменты сервера недоступны, пока вы его не авторизуете.

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

1. Добавьте сервер, требующий аутентификации

Если вы уже добавили сервер sentry в быстром старте MCP, пропустите этот шаг: повторный запуск claude mcp add с тем же именем сервера в той же области действия завершится ошибкой MCP server sentry already exists in local config. В противном случае запустите:

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

2. Используйте команду /mcp в Claude Code

В Claude Code используйте команду:

/mcp

Затем следуйте инструкциям в вашем браузере для входа.

[!TIP]

Советы:

• Токены аутентификации хранятся безопасно и автоматически обновляются
• Используйте "Clear authentication" в меню /mcp для отзыва доступа
• Если ваш браузер не открывается автоматически, скопируйте предоставленный URL и откройте его вручную
• Если перенаправление браузера не удаётся с ошибкой подключения после аутентификации, вставьте полный URL обратного вызова из адресной строки браузера в поле ввода URL, которое появляется в Claude Code
• Аутентификация OAuth работает с HTTP-серверами

Аутентификация из командной строки

Команда claude mcp login <name> запускает поток OAuth настроенного сервера непосредственно из вашей оболочки, поэтому вам не нужно открывать панель /mcp внутри сессии. Для коннектора claude.ai следуйте инструкциям из раздела Повторная авторизация коннектора из оболочки.

claude mcp login sentry

Чтобы позже очистить сохранённые учётные данные, запустите claude mcp logout <name>.

claude mcp login обнаруживает, когда локальный браузер недоступен, например во время сессии SSH или на Linux без сервера отображения, и выводит URL авторизации вместо попытки открыть браузер. Откройте URL на вашей локальной машине, затем вставьте полный URL перенаправления из адресной строки браузера обратно в поле ввода. Команде требуется интерактивный терминал для шага вставки, поэтому подключитесь с ssh -t. Передайте --no-browser, чтобы принудительно использовать ввод URL даже при обнаружении локального браузера.

claude mcp login sentry --no-browser

Используйте фиксированный порт обратного вызова OAuth

Некоторые MCP-серверы требуют определённый URI перенаправления, зарегистрированный заранее. По умолчанию Claude Code выбирает случайный доступный порт для обратного вызова OAuth. Используйте --callback-port, чтобы зафиксировать порт так, чтобы он соответствовал предварительно зарегистрированному URI перенаправления формы http://localhost:PORT/callback. Если вход на Claude Code v2.1.229 не удаётся с несоответствием URI перенаправления, см. примечание о версии в разделе Используйте предварительно настроенные учётные данные OAuth.

Вы можете использовать --callback-port отдельно (с динамической регистрацией клиента) или вместе с --client-id (с предварительно настроенными учётными данными).

# Fixed callback port with dynamic client registration
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

Используйте предварительно настроенные учётные данные OAuth

Некоторые MCP-серверы не поддерживают автоматическую настройку OAuth через Dynamic Client Registration. Если вы видите ошибку типа "Incompatible auth server: does not support dynamic client registration," сервер требует предварительно настроенные учётные данные. Claude Code также поддерживает серверы, которые используют Client ID Metadata Document (CIMD) вместо Dynamic Client Registration, и обнаруживает их автоматически. Если автоматическое обнаружение не удаётся, сначала зарегистрируйте приложение OAuth через портал разработчика сервера, затем предоставьте учётные данные при добавлении сервера.

1. Зарегистрируйте приложение OAuth на сервере

Создайте приложение через портал разработчика сервера и запишите ваш ID клиента и секрет клиента.

Если форма регистрации запрашивает URI перенаправления, выберите любой доступный порт и введите http://localhost:PORT/callback с этим портом. Вы будете использовать тот же порт на следующем шаге.

В v2.1.229 Claude Code вместо этого отправлял http://127.0.0.1:PORT/callback, и серверы, которые требуют точного совпадения с зарегистрированным URI перенаправления, отклоняли вход с несоответствием URI перенаправления. Claude Code v2.1.231 восстановил форму localhost. Чтобы исправить ситуацию на v2.1.229, обновите Claude Code или временно добавьте форму http://127.0.0.1:PORT/callback к зарегистрированным URI перенаправления сервера.

2. Добавьте сервер с вашими учётными данными

Вкладки охватывают обе команды: claude mcp add принимает ваш ID клиента и порт обратного вызова как флаги, а claude mcp add-json принимает их в объекте oauth. Если вы зарегистрировали URI перенаправления, установите порт обратного вызова на порт в этом URI.

[tab] claude mcp add

Используйте --client-id для передачи ID клиента вашего приложения. Флаг --client-secret запрашивает секрет с замаскированным вводом:

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

[tab] claude mcp add-json

Включите объект oauth в конфигурацию JSON и передайте --client-secret как отдельный флаг:

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
  --client-secret

[tab] claude mcp add-json (только порт обратного вызова)

Чтобы зафиксировать только порт обратного вызова и позволить Claude Code зарегистрировать клиента автоматически, установите callbackPort отдельно:

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

[tab] CI / переменная окружения

Установите секрет через переменную окружения, чтобы пропустить интерактивный запрос:

MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

3. Аутентификация в Claude Code

Запустите /mcp в Claude Code и следуйте потоку входа в браузере.

[!TIP]

Советы:

• Секрет клиента хранится безопасно в связке ключей вашей системы (macOS) или файле учётных данных, а не в вашей конфигурации
• Вы можете установить секрет клиента только при добавлении сервера. Когда вы аутентифицируетесь с claude mcp login или из /mcp, Claude Code использует сохранённый секрет, не запрашивает его и не читает MCP_CLIENT_SECRET
• Чтобы позже добавить или изменить секрет, удалите сервер с claude mcp remove <name>, затем добавьте его снова с --client-secret и тем же --scope
• Если сервер использует публичный OAuth-клиент без секрета, используйте только --client-id без --client-secret
• Эти флаги применяются только к транспортам HTTP и SSE. Они не влияют на серверы stdio
• Используйте claude mcp get <name> для проверки того, что учётные данные OAuth настроены для сервера

Переопределите обнаружение метаданных OAuth

Укажите Claude Code определённый URL метаданных сервера авторизации OAuth, чтобы обойти цепочку обнаружения по умолчанию. Установите authServerMetadataUrl, когда стандартные эндпоинты MCP-сервера выдают ошибки или когда вы хотите маршрутизировать обнаружение через внутренний прокси. По умолчанию Claude Code сначала проверяет RFC 9728 Protected Resource Metadata на /.well-known/oauth-protected-resource, затем возвращается к RFC 8414 authorization server metadata на /.well-known/oauth-authorization-server.

Установите authServerMetadataUrl в объекте oauth конфигурации вашего сервера в .mcp.json:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

URL должен использовать https://. scopes_supported из URL метаданных переопределяет scope, которые объявляет вышестоящий сервер.

Ограничьте scope OAuth

Установите oauth.scopes, чтобы зафиксировать scope, которые Claude Code запрашивает во время потока авторизации. Это поддерживаемый способ ограничить MCP-сервер подмножеством, одобренным командой безопасности, когда вышестоящий сервер авторизации объявляет больше scope, чем вы хотите предоставить. Значение — это одна строка с разделением пробелами, соответствующая формату параметра scope в RFC 6749 §3.3.

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

oauth.scopes имеет приоритет над authServerMetadataUrl и над scope, которые сервер обнаруживает на /.well-known. Оставьте его неустановленным, чтобы позволить MCP-серверу определить запрашиваемый набор scope.

Когда oauth.scopes не установлен, Claude Code не запрашивает полный каталог scopes_supported из автоматически обнаруженных метаданных сервера авторизации. Метаданные, полученные из настроенного authServerMetadataUrl, по-прежнему предоставляют свой scopes_supported в качестве запрашиваемых scope.

Если сервер авторизации объявляет offline_access в scopes_supported, Claude Code добавляет его к зафиксированным scope, чтобы токен доступа можно было обновить без нового входа в браузере.

Если сервер позже возвращает 403 insufficient_scope для вызова инструмента, вызов завершается ошибкой с сообщением needs additional permissions, в котором указан scope, запрашиваемый сервером. Сервер показывается как требующий аутентификации в /mcp.

Если этого scope нет в вашем зафиксированном oauth.scopes, добавьте его, затем запустите /mcp и аутентифицируйте сервер снова. Claude Code запрашивает зафиксированные scope, а не scope, названный сервером, поэтому если вы аутентифицируетесь снова, не добавив его, полученный токен по-прежнему не будет его содержать.

Используйте OAuth с сервером за прокси с аутентификацией

Если ваш MCP-сервер использует OAuth за прокси или шлюзом, который проверяет собственный заголовок, вход завершается ошибкой, когда запросы OAuth приходят без этого заголовка. Для входа через прокси требуется Claude Code v2.1.299 или новее, причём должны быть настроены и заголовок, и вход:

• Заголовок прокси: передайте его с помощью --header, поля headers или headersHelper под именем, которое читает прокси
• Вход через OAuth: не включайте Authorization в настроенные заголовки, затем войдите с помощью claude mcp login <name> в вашей оболочке. Если вы настроите заголовок Authorization, Claude Code использует его как учётные данные сервера и не возвращается к OAuth для этого сервера.

Используйте динамические заголовки для пользовательской аутентификации

Когда для аутентификации, такой как Kerberos, краткосрочные токены или внутреннее SSO, нужны заголовки, генерируемые во время подключения, задайте в headersHelper сервера команду. Claude Code запускает её при подключении и объединяет её вывод с отправляемыми заголовками. В этом примере используется скрипт:

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

Команда также может быть встроенной:

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"
    }
  }
}

Требования:

• Команда должна записать в stdout объект JSON из строковых пар ключ-значение
• Claude Code запускает команду в оболочке и прекращает её ожидание через 10 секунд
• Claude Code выбирает рабочий каталог команды по месту, где вы настроили сервер, поэтому указывайте скрипт абсолютным путём или поместите его в PATH
• Динамические заголовки переопределяют любые статические headers с тем же именем

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

Если вызов инструмента возвращает 401 Unauthorized или 403 Forbidden, Claude Code автоматически повторно запускает помощника по тому же правилу, переподключается со свежими заголовками и повторяет вызов один раз. Claude Code помечает сервер как требующий аутентификации в /mcp, только если эта повторная попытка также не удаётся.

Когда вывод помощника включает заголовок Authorization, Claude Code использует эти учётные данные как аутентификацию сервера и не возвращается к OAuth для этого сервера.

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

Claude Code устанавливает эти переменные окружения при выполнении помощника:

Используйте их для написания одного скрипта помощника, который обслуживает несколько MCP-серверов.

headersHelper, предоставленный плагином, не может ссылаться на значения ${user_config.*} плагина, потому что команда запускается через оболочку. Claude Code сообщает о неправильной конфигурации сервера с ошибкой и не подставляет значение. Вместо этого поместите ${user_config.KEY} в поле headers сервера, которое не анализируется оболочкой, или пусть скрипт помощника читает значение из файла конфигурации. До v2.1.207 headersHelper подставлял значения ${user_config.*}.

Где запускается помощник

Claude Code выбирает рабочий каталог команды headersHelper из конфигурации, которая объявляет сервер. cd, который Claude выполняет в Bash, не меняет его, а /cd меняет его только для серверов, которые запускаются из основного рабочего каталога сессии. Каждая строка ниже указывает каталог, относительно которого разрешается относительный путь в вашей команде headersHelper.

До v2.1.238 Claude Code также запускал помощников серверов пользовательского уровня, управляемых серверов и коннекторов claude.ai, а также файлов агентов извне вашего проекта из каталога, в котором вы его запустили.

Какие переменные может читать помощник

headersHelper, который поставляет репозиторий или плагин, — это команда, которую вы не писали, поэтому Claude Code запускает её без переменных с учётными данными из вашего окружения, таких как ANTHROPIC_API_KEY. Место, где вы настроили сервер, определяет, применяется ли это:

• Удаляются: сервер в проектном .mcp.json или в плагине, а также встроенный сервер в файле агента из вашего проекта или из каталога --add-dir
• Не удаляются: сервер на пользовательском или локальном уровне, в управляемом MCP, из коннектора claude.ai или предоставленный SDK или --mcp-config, а также встроенный сервер в файле агента из ~/.claude/agents/, из управляемых настроек или переданный с --agents

За исключением переменных Git GIT_CONFIG_KEY_<n>, Claude Code удаляет из вашего окружения каждую переменную, имя которой похоже на учётные данные, например имя, содержащее TOKEN, SECRET, PASSWORD, KEY или AUTH в любом регистре, поэтому и ANTHROPIC_API_KEY, и MY_REGISTRY_TOKEN удаляются. Claude Code также удаляет фиксированный список переменных с учётными данными, имена которых не следуют этому шаблону, например ANTHROPIC_CUSTOM_HEADERS.

Если это относится к вашему помощнику, пусть скрипт читает учётные данные из файла или хранилища учётных данных. Если url сервера содержит фактическое значение одной из этих переменных, например MY_REGISTRY_TOKEN, то в значении CLAUDE_CODE_MCP_SERVER_URL, которое получает помощник, эта часть также заменяется на REDACTED.

Доверьтесь папке перед запуском её headersHelper

Claude Code выполняет headersHelper как произвольную shell-команду. Для сервера в проектном .mcp.json или на локальном уровне он запускает помощника только после того, как вы примете диалог доверия для каталога проекта, в котором объявлен сервер. До v2.1.238 сессия claude -p или SDK запускала этих помощников без проверки доверия, а интерактивная сессия запускала их, как только вы доверились родительской папке.

• Доверие, которое не учитывается: доверие родительской папке и автоматическое доверие, которое сессия claude -p или SDK получает для хуков в файлах настроек
• Пока вы не доверитесь папке: Claude Code подключает сервер только с его статическими headers. В сессии claude -p или SDK он также выводит в stderr по одной строке headersHelper not run на каждый сервер, сообщая, как предоставить доверие.
• Доверие без диалога: установите projects["<path>"].hasTrustDialogAccepted в true в ~/.claude.json. <path> — это папка, к которой, согласно разделу Правила разрешения проекта и доверие к рабочему пространству, Claude Code привязывает доверие.

Claude Code применяет то же правило к серверу, объявленному встроенным в файл агента, проверяя, откуда взят этот файл агента: из вашего проекта, для файла в его каталоге .claude/agents/, или из каталога --add-dir. Пока вы не доверитесь самому этому проекту или каталогу, Claude Code вообще не загружает сервер, поэтому его помощник тоже никогда не запускается.

Вход на MCP-сервер за шлюзом, требующим заголовок

Вход через OAuth на MCP-сервер завершается ошибкой, когда шлюз требует заголовок, например X-API-Key, а Claude Code его не отправляет. Чтобы Claude Code отправлял этот заголовок, добавьте его в конфигурацию сервера и используйте Claude Code v2.1.299 или новее:

• Сервер, конфигурацию которого вы можете редактировать: задайте заголовок в headers или возвращайте его из headersHelper
• Сервер, который предоставляет управляемый MCP или плагин: попросите администратора или автора плагина добавить заголовок в запись сервера

После этого Claude Code добавляет настроенные заголовки, кроме Authorization, к запросам входа, обновления токена и отзыва токена, которые он отправляет на origin сервера. Origin сервера — это схема, хост и порт в его url. Шлюз, требующий заголовок, всё равно может остановить вход на странице авторизации или на сервере авторизации с другим origin:

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

Добавьте MCP servers из конфигурации JSON

Если у вас есть конфигурация JSON для MCP server, вы можете добавить ее напрямую:

1. Добавьте MCP server из JSON

# Базовый синтаксис
claude mcp add-json <name> '<json>'

# Пример: добавление HTTP server с конфигурацией JSON
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# Пример: добавление stdio server с конфигурацией JSON
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

# Пример: добавление HTTP server с предварительно настроенными учетными данными OAuth
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

2. Проверьте, что server был добавлен

claude mcp get weather-api

[!TIP]

Советы:

• Убедитесь, что JSON правильно экранирован в вашей оболочке
• JSON должен соответствовать схеме конфигурации MCP server
• Вы можете использовать --scope user для добавления server в вашу конфигурацию пользователя вместо конфигурации, специфичной для проекта

Импортируйте MCP servers из Claude Desktop

Если вы уже настроили MCP servers в Claude Desktop, вы можете их импортировать:

1. Импортируйте servers из Claude Desktop

# Базовый синтаксис 
claude mcp add-from-claude-desktop 

2. Выберите, какие servers импортировать

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

3. Проверьте, что servers были импортированы

claude mcp list 

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

[!TIP]

Советы:

• Эта функция работает только на macOS и Windows Subsystem for Linux (WSL)
• Она читает файл конфигурации Claude Desktop из его стандартного расположения на этих платформах
• Используйте флаг --scope user для добавления servers в вашу конфигурацию пользователя
• Импортированные servers сохраняют те же имена, что и в Claude Desktop, когда имя содержит только буквы, цифры, дефисы и подчеркивания. Claude Code сообщает о server, имя которого содержит любой другой символ, и пропускает его
• Если servers с одинаковыми именами уже существуют, они получат числовой суффикс (например, server_1)

Использование MCP серверов из claude.ai

Если вы вошли в Claude Code с помощью учётной записи claude.ai, MCP серверы, которые вы добавили в claude.ai, известные как connectors, автоматически доступны в Claude Code:

1. Настройте MCP серверы в claude.ai

Добавьте серверы на claude.ai/customize/connectors. В планах Team и Enterprise только администраторы могут добавлять серверы.

2. Аутентифицируйте MCP сервер

Выполните все необходимые шаги аутентификации в claude.ai.

3. Просмотрите и управляйте серверами в Claude Code

В Claude Code используйте команду:

/mcp

Серверы из claude.ai появляются в списке с индикаторами, показывающими, что они поступают из claude.ai.

Anthropic также предоставляет некоторые коннекторы самостоятельно, без добавления вами или администратором. На учётных записях, где доступен Claude Docs, /mcp отображает claude.ai Claude Docs без какой-либо настройки, и Claude использует его, когда вы просите документ, предназначенный для других людей. Чтобы отключить только этот коннектор, см. раздел Отключение коннекторов claude.ai.

Claude Code помечает connector как managed в /mcp и в менеджере /plugin когда ваша организация управляет его аутентификацией в claude.ai. Статус managed не изменяет способ подключения Claude Code к connector или применение инструментов управления вашей организации.

Connectors, в которые вы никогда не входили, свёрнуты за строкой Show unused connectors в конце раздела claude.ai, поэтому список, предоставленный организацией, не заполняет панель. Выберите строку, чтобы развернуть их. Connector, в который вы входили ранее, остаётся видимым даже если в настоящий момент требуется повторная аутентификация.

Connectors из claude.ai загружаются только когда ваш активный метод аутентификации — это вход по подписке claude.ai. Они не загружаются, даже если вы ранее запустили /login, когда:

• ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN или apiKeyHelper активны
• Активен сторонний поставщик, такой как Amazon Bedrock или Agent Platform Google Cloud
• ANTHROPIC_PROFILE, переменные федерации или активный профиль Anthropic предоставляют учётные данные
• CLAUDE_CODE_OAUTH_TOKEN содержит токен из claude setup-token, который может только делать запросы к модели

Если /mcp не отображает connector, который вы добавили, запустите /status, чтобы подтвердить, какой метод аутентификации активен. Отмените установку этой переменной окружения, удалите параметр apiKeyHelper или отключите профиль, затем запустите /login, чтобы выбрать вашу учётную запись claude.ai.

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

Если /mcp показывает connector как session token rejected, или его подробное представление показывает claude.ai rejected the session token, claude.ai отклонил токен из вашего входа в Claude Code. Повторная авторизация connector не очищает это состояние, потому что собственная авторизация connector в claude.ai — это не то, что было отклонено. Чтобы очистить это:

1. Запустите /login, чтобы войти снова.
2. Переподключите connector из /mcp.

До версии 2.1.222 Claude Code помечал connectors как требующие аутентификации, и их авторизация не решала проблему.

Сервер, который вы добавили в Claude Code, имеет приоритет над connector из claude.ai, который указывает на тот же URL. Когда это происходит, /mcp отображает connector как скрытый и показывает, как удалить дубликат, если вы предпочитаете использовать connector.

Некоторые размещённые Anthropic connectors, такие как Microsoft 365, Gmail и Google Calendar, не поддерживают локальный OAuth из Claude Code, потому что вышестоящий поставщик идентификации принимает только URL перенаправления, зарегистрированный claude.ai. Когда сервер, который вы добавили с помощью claude mcp add или в .mcp.json, указывает на один из этих хостов и вы входите в него из /mcp или с помощью claude mcp login, Claude Code показывает is Anthropic-hosted and doesn't support local OAuth, направляя вас подключить сервис на claude.ai/customize/connectors вместо этого.

После удаления вашей записи с помощью claude mcp remove <name> и подключения сервиса на claude.ai, connector появляется в Claude Code автоматически.

Как connectors достигают Claude Code

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

disableClaudeAiConnectors, ENABLE_CLAUDEAI_MCP_SERVERS и allowAllClaudeAiMcps действуют только на первую строку, connectors, которые Claude Code загружает сам. Две другие строки отличаются от неё следующим образом:

• Облачные сеансы: записи allowedMcpServers и deniedMcpServers, которые достигают сеанса, например через параметры, управляемые сервером, также фильтруют доставленные connectors. Прокси сеанса переписывает URL каждого connector, поэтому шаблон serverUrl, написанный для собственного URL connector, не совпадает с ним. Чтобы допустить доставленные connectors наряду со списком разрешений URL в самостоятельной среде, добавьте записи serverUrl, указанные в разделе Трафик Connector покидает вашу сеть. Claude Code отбрасывает доставленные connectors, когда на хосте, который запускает сеанс, присутствует managed-mcp.json, например хост самостоятельного runner, независимо от того, установили ли вы allowAllClaudeAiMcps.
• Локальные и SSH сеансы настольного приложения: настольное приложение регистрирует connectors как внутрипроцессные серверы type: "sdk", и никакой параметр MCP или managed-mcp.json не достигает их. Пользователь держит connector вне своих собственных сеансов, отключив его на claude.ai/customize/connectors. Организация блокирует инструменты connector или полностью отключает Claude Code в настольном приложении.

Элементы управления организацией для инструментов connector

Ваша организация может установить элементы управления для каждого инструмента на connectors claude.ai. Claude Code читает эти параметры при запуске и применяет их локально, кроме как в локальных и SSH сеансах настольного приложения. Там настольное приложение скрывает инструменты blocked перед доставкой connector, и параметр ask не достигает Claude Code, поэтому он применяет обычные правила разрешений сеанса к этим инструментам вместо запроса при каждом вызове. В сеансах, где Claude Code загружает connectors сам, запустите /mcp, чтобы увидеть, какой параметр применяется к каждому инструменту на connector.

• Инструмент со значением ask: Claude Code запрашивает подтверждение при каждом вызове с причиной Your organization requires approval for this tool. Запрос появляется даже в режимах разрешений acceptEdits, auto и bypassPermissions. В терминале запрос не предлагает опцию запомнить ваш выбор. Правила разрешения, которые совпадают с инструментом, также не позволяют пропустить запрос. В режиме dontAsk, который никогда не запрашивает подтверждение, Claude Code вместо этого отклоняет вызов.
• Инструмент установлен на blocked: Claude Code фильтрует инструмент перед тем, как Claude его видит, поэтому он никогда не появляется в списке инструментов Claude. В сеансах, где Claude Code загружает connectors сам, список инструментов /mcp всё ещё показывает инструмент, помеченный как disabled by your organization.

Настольное приложение и чат claude.ai применяют тот же параметр blocked, поэтому Claude не может использовать инструмент там либо, и вы не можете скрыть инструмент из сеансов настольного приложения, сохраняя его доступным в чате. Настольное приложение пропускает connector, все инструменты которого заблокированы.

Отключение connectors claude.ai

Claude Code применяет disableClaudeAiConnectors только к connectors, которые он загружает сам, а не к connectors, которые доставляет облачный хост или настольное приложение. Чтобы отключить connectors, которые он загружает, установите параметр на true в любой области параметров:

{
  "disableClaudeAiConnectors": true
}

Этот параметр использует семантику any-source-true: true в любом источнике параметров имеет приоритет. Проверенный в репозитории .claude/settings.json проекта может отключить connectors, которые Claude Code загружает сам, но уровень проекта false не может повторно включить connectors, которые уровень пользователя или политики true отключил. Серверы, переданные явно через --mcp-config, не затронуты.

Вы также можете установить переменную окружения ENABLE_CLAUDEAI_MCP_SERVERS на false, что имеет тот же эффект для текущего сеанса оболочки:

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

Чтобы заблокировать отдельные connectors claude.ai вместо всех них, добавьте их в deniedMcpServers по имени или по шаблону URL. Например, запись serverName из "claude.ai Slack" блокирует connector Slack. Вы также можете запустить /mcp, чтобы переключить любой connector, который Claude Code загружает, включить или отключить только для текущего проекта.

Использование Claude Code в качестве MCP-сервера

Вы можете использовать Claude Code в качестве MCP-сервера, к которому могут подключаться другие приложения:

# Start Claude as a stdio MCP server
claude mcp serve

Команда ничего не выводит при запуске. Stdio MCP-сервер взаимодействует через stdin и stdout, поэтому молчаливый, заблокированный терминал означает, что сервер работает и ожидает подключения клиента.

Вы можете использовать это в Claude Desktop, добавив эту конфигурацию в claude_desktop_config.json:

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

[!WARNING]

Настройка пути к исполняемому файлу: поле command должно ссылаться на исполняемый файл Claude Code. Если команда claude отсутствует в PATH вашей системы, вам потребуется указать полный путь к исполняемому файлу.

Чтобы найти полный путь:

which claude

Затем используйте полный путь в вашей конфигурации:

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "/full/path/to/claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

Без правильного пути к исполняемому файлу вы столкнётесь с ошибками вроде spawn claude ENOENT.

[!TIP]

Советы:

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

Чтение вывода фоновой команды в качестве MCP-клиента

Поле backgroundOutputPath в результате Bash или PowerShell от claude mcp serve означает, что вызов оставил свою команду выполняться в фоновом режиме. Команда выполняется в фоновом режиме, когда ваш клиент задаёт run_in_background: true в вызове. Команда переднего плана также может перейти в фоновый режим, когда достигает таймаута.

Это поле находится в JSON-тексте результата и содержит путь к файлу вывода команды.

• Чтобы прочитать вывод, записанный на данный момент: откройте файл по этому пути из вашего клиента или передайте путь как file_path инструменту сервера Read
• Чтобы определить, когда команда завершилась: добавьте к значению command вызов echo с фиксированной строкой, например npm test; echo DONE. Команда завершилась, как только эта строка появится в файле. Без этой строки ничто не отмечает завершение, поскольку Claude Code не добавляет в файл заключительную строку и не уведомляет ваш клиент.
• Чтобы прочитать конец длинного вывода: Read только с file_path возвращает первую страницу или завершается ошибкой, если файл превышает ограничение по размеру. Передайте также offset и limit — это работает при любом размере файла:
  1. Вызовите Read с offset и limit, равными 1, и возьмите totalLines из результата
  2. Снова вызовите Read с offset, равным totalLines минус девять, и limit, равным 10
  3. Найдите вашу строку echo в последних десяти строках, которые возвращает второй вызов

Для поля backgroundOutputPath требуется Claude Code v2.1.295 или новее.

Ограничения и предупреждения выходных данных MCP

Когда инструменты MCP производят большие объемы выходных данных, Claude Code помогает управлять использованием токенов, чтобы не перегружать контекст вашего диалога:

• Порог предупреждения выходных данных: Claude Code отображает предупреждение, когда выходные данные любого инструмента MCP превышают 10 000 токенов
• Настраиваемый лимит: вы можете отрегулировать максимально допустимое количество токенов выходных данных MCP, используя переменную окружения MAX_MCP_OUTPUT_TOKENS
• Лимит по умолчанию: максимум по умолчанию составляет 25 000 токенов
• Область действия: переменная окружения применяется к инструментам, которые не объявляют свой собственный лимит. Инструменты, которые устанавливают anthropic/maxResultSizeChars, используют это значение вместо этого для текстового содержимого, независимо от того, какое значение установлено для MAX_MCP_OUTPUT_TOKENS. Инструменты, которые возвращают данные изображений, по-прежнему подчиняются MAX_MCP_OUTPUT_TOKENS
• Превышение лимита: когда успешный результат без содержимого изображения превышает лимит токенов, Claude Code сохраняет его в файл и заменяет его в диалоге сообщением, которое указывает путь к файлу, чтобы Claude прочитал файл, когда ему нужно содержимое. Файл находится в директории tool-results сессии в ~/.claude/projects/.
• Размер ответа от серверов HTTP и SSE: когда ответ от сервера HTTP или SSE превышает 16 МиБ, Claude Code прекращает его чтение, и запрос завершается с ошибкой. Лимит применяется после распаковки к одному телу ответа JSON или одному событию потока событий. Если вы поддерживаете сервер, возвращайте меньше данных в каждом ответе, чтобы оставаться в пределах лимита, например используя постраничную выдачу результатов
• Размер сообщения от серверов WebSocket: когда сервер WebSocket отправляет одно сообщение размером более 16 МиБ, Claude Code закрывает соединение, и выполняющиеся вызовы к этому серверу завершаются с ошибкой. Если вы поддерживаете сервер, возвращайте меньше данных в каждом сообщении, чтобы оставаться в пределах лимита

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

• Лимит символов для текстовых результатов: для инструмента, который не объявляет anthropic/maxResultSizeChars, Claude Code сохраняет успешный результат без содержимого изображения в файл, как только его длина превышает 50 000 символов, независимо от количества токенов. Настройка MAX_MCP_OUTPUT_TOKENS не изменяет этот порог
• Результаты с ошибкой: когда инструмент возвращает результат с пометкой isError: true, Claude получает текст результата как сообщение об ошибке инструмента. Если текст ошибки длиннее примерно 11 000 символов, сохраняются только его первые 5 000 и последние 5 000 символов, а между ними вставляется маркер, указывающий, сколько символов было удалено

Чтобы изменить лимит токенов, установите MAX_MCP_OUTPUT_TOKENS в своей оболочке перед запуском Claude Code:

export MAX_MCP_OUTPUT_TOKENS=50000
claude

Повысить лимит для конкретного инструмента

Если вы создаете сервер MCP, вы можете разрешить отдельным инструментам возвращать результаты, превышающие порог сохранения на диск по умолчанию в 50 000 символов, установив _meta["anthropic/maxResultSizeChars"] в записи ответа tools/list инструмента. Claude Code повышает порог этого инструмента до аннотированного значения, вплоть до жесткого потолка в 500 000 символов.

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

{
  "name": "get_schema",
  "description": "Returns the full database schema",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

Аннотация применяется независимо от MAX_MCP_OUTPUT_TOKENS для текстового содержимого, поэтому пользователям не нужно повышать переменную окружения для инструментов, которые ее объявляют. Инструменты, которые возвращают данные изображений, по-прежнему подчиняются лимиту токенов.

Изображения в результатах инструментов

Когда инструмент MCP возвращает изображение PNG, JPEG, GIF или WebP, Claude видит изображение встроенным в диалог. Встроенная копия может быть уменьшена или сжата, чтобы соответствовать ограничениям размера изображения модели. Claude Code также сохраняет исходные байты в файл в директории tool-results сессии в ~/.claude/projects/ и предоставляет Claude путь к файлу. Claude затем может обрезать, конвертировать или повторно использовать файл в полном разрешении с помощью инструментов, таких как Bash.

Если вы отключите сохранение сессии с помощью --no-session-persistence или CLAUDE_CODE_SKIP_PROMPT_HISTORY, Claude Code не будет записывать файл изображения, и Claude получит только встроенную копию.

Сохранение результатов изображений MCP в файл требует Claude Code версии 2.1.283 или более поздней.

Схемы входных данных инструментов с комбинатором корневого уровня

Некоторые серверы MCP объявляют схему входных данных инструмента как объединение JSON Schema с anyOf, oneOf или allOf на верхнем уровне схемы. Claude API не принимает эти ключевые слова в корне схемы. Он принимает комбинаторы, вложенные в properties, которые Claude Code отправляет без изменений.

Инструменты с комбинатором корневого уровня остаются доступными. Перед отправкой инструмента в API, Claude Code преобразует схему в один объект и добавляет предложение к описанию инструмента, которое указывает Claude, какие группы параметров принадлежат друг другу:

• allOf: свойства из каждой ветви объединяются, и список required каждой ветви по-прежнему применяется
• anyOf и oneOf: свойства из каждой ветви объединяются, и список required каждой ветви описывается в описании инструмента вместо того, чтобы быть принудительно применяемым схемой

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

Когда Claude Code не может создать схему, которую принимает API, или при развёртывании, которое не получает удалённую конфигурацию, включающую переписывание, он пропускает этот инструмент, записывает причину в журнал сервера и оставляет другие инструменты сервера доступными.

Инструменты с недействительными схемами входных данных

[!NOTE]

Если ваша сессия завершается ошибкой 400, в которой инструмент указан по его позиции, выполните шаги из раздела Схема входных данных инструмента недействительна.

Если у одного из инструментов вашего MCP-сервера схема входных данных нарушает одно из двух правил, которые применяет API, Claude Code исключает этот инструмент. Другие инструменты сервера это не затрагивает. Claude Code проверяет оба правила при загрузке инструментов сервера:

• Имена свойств верхнего уровня должны быть длиной от 1 до 64 символов и использовать только буквы и цифры ASCII, _, . и -
• Схема должна быть действительной в соответствии с метасхемой JSON Schema draft 2020-12. Claude Code применяет эту проверку к схемам, которые не объявляют $schema, и к схемам, которые объявляют draft 2020-12. Схема, которая объявляет любой другой диалект, пропускает эту проверку, хотя проверка имен свойств выше все еще применяется

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

Когда получение флагов функций отключено или флаги так и не поступили, например на изолированной машине, инструмент, нарушающий правило, не исключается:

• Claude получает инструмент без изменений, а в лог сервера для него записывается input schema would be rejected by the Anthropic API
• Если затем API отклонит схему, см. раздел Инструменты, схему входных данных которых отклоняет API

До версии 2.1.216 ни одно развёртывание не запускало эти проверки.

Обработка комбинатора корневого уровня отделена и сохраняет свое собственное поведение, когда получение флагов отключено или флаги никогда не поступали.

Инструменты, схему входных данных которых отклоняет API

Если строка в отладочном логе содержит the API refused this tool's input schema, в ней указан инструмент, схему которого API отклонил в запросе. Claude Code повторно отправляет этот запрос, объявив инструмент без параметров.

• Если ваша сессия завершается ошибкой 400, в которой инструмент указан по его позиции: выполните шаги из раздела Схема входных данных инструмента недействительна
• Если вы используете сервер: вам ничего не нужно делать. Claude по-прежнему может вызывать инструмент, но не видит его параметров
• Если вы поддерживаете сервер: исправьте схему входных данных инструмента на сервере. Строка лога заканчивается на The API said: и причиной, по которой API отклонил схему. Проверяйте аргументы, которые получает сервер, поскольку Claude вызывает инструмент, не видя его параметров

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

Инструменты с именами длиннее 128 символов

Если /mcp показывает инструмент, который Claude не может вызвать, проверьте, не превышает ли полное имя инструмента 128 символов. Выполните /mcp в своей сессии и выберите инструмент, чтобы увидеть его полное имя, например mcp__<server>__<tool>. Claude Code не включает инструмент MCP в список инструментов, отправляемых Claude, если его полное имя длиннее 128 символов. Claude API отклоняет запрос, содержащий такой инструмент, поэтому исключение этого инструмента позволяет остальным инструментам сервера продолжать работать.

Сообщение, в котором указывается этот инструмент, и способы сократить его полное имя описаны в разделе Имя инструмента MCP длиннее 128 символов.

Требование подтверждения для конкретного инструмента

Если вы создаёте MCP-сервер, вы можете отметить инструмент как требующий явного подтверждения при каждом вызове, установив _meta["anthropic/requiresUserInteraction"] в значение true в записи инструмента в ответе tools/list. Значение должно быть логическим значением JSON true; любое другое значение игнорируется.

Claude Code показывает запрос разрешения этого инструмента при каждом вызове, даже в режимах разрешений acceptEdits, auto и bypassPermissions, и не предлагает для него опцию «не спрашивать снова». Разрешающие правила, которые соответствуют инструменту, также не позволяют пропустить запрос. В режиме dontAsk, который никогда не выводит запросы, Claude Code вместо этого отклоняет вызов.

Запрос должен дойти до человека. В неинтерактивном режиме с --permission-prompt-tool результат allow из инструмента запроса разрешения для отмеченного инструмента преобразуется в отклонение с сообщением MCP tool requires user interaction; not supported via --permission-prompt-tool. Обратный вызов canUseTool Agent SDK получает эти вызовы и может их подтвердить, потому что ваше приложение SDK должно показывать их пользователю.

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

Следующая запись tools/list отмечает один инструмент как всегда требующий подтверждения.

{
  "name": "grant_access",
  "description": "Requests access to a protected resource",
  "_meta": {
    "anthropic/requiresUserInteraction": true
  }
}

Некоторые интерфейсы, такие как Remote Control и приложения, созданные на основе Agent SDK, обычно позволяют вам подтверждать вызовы инструментов одним касанием. Для инструмента, отмеченного этой аннотацией, Claude Code скрывает действие одного касания и вместо этого показывает полный запрос разрешения инструмента, поэтому подтверждение по-прежнему исходит от человека, отвечающего на запрос, а не от касания.

Claude Code таким же образом скрывает подтверждение одним касанием для любого запроса разрешения, который может полностью отобразить только диалог терминала, например запроса, содержащего предупреждение безопасности или опцию «всегда разрешать», которую удалённый интерфейс не может показать. Вы отвечаете на такой запрос в диалоге терминала, а не из Remote Control.

Помечайте инструменты, которые безопасно вызывать дважды

Если вы создаёте MCP-сервер, помечайте инструменты, которые безопасно вызывать дважды, чтобы Claude Code мог повторить вызов, ожидавший ответа в момент закрытия соединения. Claude Code может один раз повторить такой вызов к HTTP-серверу или коннектору claude.ai через новое соединение. Вызов, который Claude Code не повторяет, может завершиться ошибкой connection closed before the tool call was answered.

Чтобы пометить инструмент, установите одну из этих annotations в значение true в его записи tools/list:

• idempotentHint: инструмент может что-то изменять, и повторный вызов с теми же аргументами безопасен
• readOnlyHint: инструмент ничего не изменяет. Claude Code также выполняет вызовы такого инструмента параллельно с другими вызовами только для чтения.

Например, эти поля в записи tools/list помечают инструмент set_issue_status как безопасный для повторного вызова:

{
  "name": "set_issue_status",
  "annotations": {
    "idempotentHint": true
  }
}

Ответ на запросы elicitation MCP

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

Серверы могут запрашивать ввод двумя способами:

• Режим формы: Claude Code показывает диалог с полями формы, определенными сервером (например, запрос имени пользователя и пароля). Заполните поля и отправьте.
• Режим URL: Claude Code спрашивает, открыть ли ссылку в вашем браузере. Серверы используют этот режим для потока, который завершается вне терминала, например для входа в систему.

В режиме URL Claude Code передает URL в качестве аргумента командной строки обработчику URL вашей системы и ограничивает длину этого аргумента. Когда URL, после экранирования для командной строки, превышает это ограничение, вы можете только отклонить запрос. Каждый символ, который требует экранирования, такой как % или &, считается четыре раза в сторону ограничения: сам символ плюс три символа экранирования. URL без них достигает ограничения примерно на 8000 символов. URL, построенный в основном из процентных экранирований, где каждый третий символ — это %, достигает его примерно на 4000.

Для автоматического ответа на запросы elicitation без отображения диалога используйте hook Elicitation.

Если вы создаете MCP сервер, который использует elicitation, см. спецификацию MCP elicitation для деталей протокола и примеров схемы.

Ответ на запрос elicitation в облачной сессии

Когда задача Claude в вашей облачной сессии ожидает ответа на запрос MCP-сервера, серверу что-то нужно от вас, например значение или вход в систему. Если запрос отображается в виде карточки на claude.ai/code или на вкладке Code в приложении Desktop, ответьте на карточке:

• Режим формы: заполните поля, затем нажмите Submit
• Режим URL: нажмите Open link, завершите открывшийся поток, затем нажмите I’m done, continue на карточке

Чтобы отказаться от запроса, нажмите Decline. Claude продолжит работу, как только сервер ответит.

Если вы не видите карточку ни в одном из этих мест, вы не можете ответить на запрос там. В своей собственной сессии нажмите там кнопку остановки, чтобы завершить ход.

Режимы elicitation, которые объявляет Claude Code

Если вы создаете MCP-сервер, возможности клиента, которые Claude Code отправляет при подключении, сообщают вашему серверу, какие режимы elicitation он может запрашивать. Claude Code объявляет elicitation: {form: {}, url: {}} на следующих соединениях, поэтому сервер на любом из них может запрашивать оба режима:

• Соединения, которые используют ревизию протокола 2026-07-28
• Соединения на более ранних ревизиях протокола, 2025-11-25 и старше, с серверами stdio, sse, http и ws в конфигурации MCP Claude Code пользователя. Требуется Claude Code v2.1.287 или новее

На остальных своих соединениях на более ранних ревизиях, например с коннекторами claude.ai, Claude Code объявляет пустое elicitation: {}, что разрешает запросы elicitation только в режиме формы.

Сервер, созданный на Java MCP SDK 0.17.0 или более ранней версии, может отклонить объявление, содержащее form и url. См. MCP server rejected the elicitation capability.

Использование ресурсов MCP

Серверы MCP могут предоставлять ресурсы, на которые вы можете ссылаться с помощью упоминаний @, аналогично тому, как вы ссылаетесь на файлы.

Ссылка на ресурсы MCP

1. Список доступных ресурсов

Введите @ в вашу подсказку, чтобы увидеть доступные ресурсы со всех подключённых серверов MCP. Ресурсы отображаются рядом с файлами в меню автодополнения.

2. Ссылка на конкретный ресурс

Используйте формат @server:protocol://resource/path для ссылки на ресурс:

Can you analyze @github:issue://123 and suggest a fix?

Please review the API documentation at @docs:file://api/authentication

3. Несколько ссылок на ресурсы

Вы можете ссылаться на несколько ресурсов в одной подсказке:

Compare @postgres:schema://users with @docs:file://database/user-model

[!TIP]

Советы:

• Ресурсы автоматически загружаются и включаются в качестве вложений при ссылке на них
• Пути ресурсов поддерживают нечёткий поиск в автодополнении упоминаний @
• Claude Code автоматически предоставляет инструменты для списания и чтения ресурсов MCP, когда серверы их поддерживают
• Ресурсы могут содержать любой тип контента, который предоставляет сервер MCP (текст, JSON, структурированные данные и т. д.)

Ресурсы MCP Apps UI — это записи с URI ui:// или типом мультимедиа text/html;profile=mcp-app: страницы для отображения хост-приложением, а не контент для чтения Claude. Они не отображаются в предложениях @ или в результатах инструмента списка ресурсов, и сервер, предлагающий только ресурсы UI, показывает пустой список ресурсов. Чтение ресурса UI по его URI по-прежнему работает.

Масштабирование с помощью поиска инструментов MCP

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

[!NOTE]

Поиск инструментов не поддерживается на Microsoft Foundry развёртываниях, размещённых на Azure, которые отклоняют его на стороне сервера: Claude Code обнаруживает отклонение и загружает инструменты MCP заранее для этого развёртывания. ENABLE_TOOL_SEARCH не может переопределить это, так как отклонение исходит от самого развёртывания.

Поиск инструментов для авторов серверов MCP

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

Добавьте чёткие, описательные инструкции сервера, которые объясняют:

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

Claude Code обрезает описание инструмента или инструкции сервера, превышающие эти лимиты по умолчанию, и Claude видит только текст до места обрезки:

• Инструкции сервера и описание инструмента, загружаемого заранее: 4 096 символов
• Описание инструмента, который Claude загружает через поиск инструментов: 16 384 символа

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

До v2.1.296 более короткий лимит составлял 2 048 символов, а до v2.1.295 он применялся к описанию каждого инструмента, включая загружаемые через поиск инструментов.

Изменение лимитов длины описаний

Чтобы изменить лимиты по умолчанию в 4 096 и 16 384 символа для серверов MCP в вашей сессии, установите CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH на количество символов. Claude Code использует это число для обоих лимитов. Например, со значением 8192 вы повышаете лимит в 4 096 символов для инструкций сервера и описаний инструментов, загружаемых заранее, и понижаете лимит в 16 384 символа для описаний инструментов, загружаемых через поиск инструментов. Эта переменная требует Claude Code v2.1.280 или позже.

Описания и инструкции некоторых серверов MCP, которые Anthropic размещает на api.anthropic.com, доходят до Claude полностью, и установка этой переменной их не обрезает.

Пометка инструмента для загрузки заранее или отложенной загрузки

Чтобы управлять тем, как загружается один из инструментов вашего сервера, задайте "anthropic/alwaysLoad" в объекте _meta этого инструмента. Человек, который добавляет ваш сервер в Claude Code, также может задать alwaysLoad для всего сервера в своей конфигурации, и его настройка может переопределить вашу:

Следующая запись tools/list запрашивает загрузку одного инструмента заранее:

{
  "name": "search_tickets",
  "description": "Searches the ticket tracker by keyword",
  "_meta": {
    "anthropic/alwaysLoad": true
  }
}

Настройка поиска инструментов

Поиск инструментов включён по умолчанию: инструменты MCP отложены и обнаруживаются по требованию.

Установка CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS отключает поиск инструментов. Вы не можете переопределить это, установив ENABLE_TOOL_SEARCH самостоятельно. На Claude Code v2.1.227 или позже ваша организация может оставить поиск инструментов включённым при этой переменной через управляемые настройки. В сессии, которая получает конфигурацию HIPAA, поиск инструментов отключён, и ни ENABLE_TOOL_SEARCH, ни управляемые настройки не включают его снова. Отключение предварительных возможностей охватывает, где применяется переопределение и что переменная удаляет.

Claude Code использует поиск инструментов на Claude Opus 4, Claude Sonnet 4, Claude Haiku 4.5 и более поздних моделях или на Opus 4.5, Sonnet 4.5, Haiku 4.5 и более поздних моделях на Agent Platform Google Cloud. На более ранних моделях Claude Code загружает все инструменты MCP заранее, и ENABLE_TOOL_SEARCH=true не переопределяет это.

На Agent Platform Google Cloud Claude Code решает по поколению модели:

• Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 и позже: поиск инструментов включён по умолчанию, как и на API Anthropic.
• Более ранние модели Agent Platform: Claude Code загружает все инструменты MCP заранее, потому что их стеки обслуживания отклоняют требуемый заголовок бета-версии. ENABLE_TOOL_SEARCH=true не переопределяет это.

До версии 2.1.221 Claude Code отключал поиск инструментов для всех моделей на Agent Platform Google Cloud, если вы не установили ENABLE_TOOL_SEARCH=true.

Управляйте поведением поиска инструментов с помощью переменной окружения ENABLE_TOOL_SEARCH:

# Использование пользовательского порога 5%
ENABLE_TOOL_SEARCH=auto:5 claude

# Полное отключение поиска инструментов
ENABLE_TOOL_SEARCH=false claude

Или установите значение в поле settings.json env.

Вы также можете отключить инструмент ToolSearch специально:

{
  "permissions": {
    "deny": ["ToolSearch"]
  }
}

Если вы запретите ToolSearch или не включите его в --tools, инструменты MCP вместо этого загружаются заранее, но запрос всё равно может содержать запись-заглушку defer_loading. Если шлюз отклоняет эту запись, см. Поиск инструментов через LLM-шлюз.

Поиск инструментов через LLM-шлюз

[!NOTE]

Эти случаи рассматриваются в других разделах:

• Вы установили CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: см. как это влияет на поиск инструментов
• Запрос завершился ошибкой, в которой упоминается defer_loading или tool_reference: см. Extra inputs are not permitted

Когда ANTHROPIC_BASE_URL указывает на шлюз, Claude Code ожидает, что шлюз будет пересылать поля инструментов defer_loading и блоки tool_reference вместе с заголовком anthropic-beta. За шлюзом поиск инструментов включён по умолчанию, поэтому инструменты MCP отложены, а запросы содержат эти поля и блоки. До v2.1.304 поиск инструментов за шлюзом был отключён, если только ENABLE_TOOL_SEARCH не имел значение true, auto или auto:N.

На v2.1.305 или позже Claude Code может повторить запрос без поиска инструментов после ответа 400 или 422. Когда повторная попытка срабатывает, на экране ничего не отображается и вам не нужно ничего делать: инструменты MCP вместо этого загружаются заранее. Позже Claude Code снова пробует поиск инструментов ценой ещё одного отклонённого запроса.

Инструменты, которые остаются отложенными ниже порога ENABLE_TOOL_SEARCH=auto

Если /context помечает инструменты как (deferred) или (loaded on-demand), хотя их определения в сумме ниже порога auto, значит, поиск инструментов уже был включён в этом диалоге и остался включённым. Сумма может уменьшиться позже, например пока серверы MCP повторно подключаются после возобновления сессии. Вам не нужно ничего делать: Claude загружает каждый из этих инструментов, когда он нужен для задачи.

Исключение сервера из отложения

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

Следующая запись .mcp.json исключает один HTTP-сервер, оставляя другие серверы отложенными:

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

Поле alwaysLoad доступно на всех типах серверов.

Установка alwaysLoad: true также заставляет запуск ждать инструментов сервера, ограниченных стандартным таймаутом подключения в 5 секунд, так как они должны присутствовать при построении первого промпта. Удалённый сервер с действительной записью cached предоставляет свои инструменты из кэша без подключения, поэтому он не задерживает запуск. Другие серверы подключаются в фоновом режиме по умолчанию; установите MCP_CONNECTION_NONBLOCKING=0, чтобы запуск ждал и их тоже.

Отложение инструментов сервера

Чтобы все инструменты сервера оставались за поиском инструментов, задайте "alwaysLoad": false в записи этого сервера в вашей конфигурации MCP. Это относится и к инструментам, которые автор сервера пометил для загрузки заранее. Если не указывать alwaysLoad, эти помеченные инструменты загружаются заранее. Требуется Claude Code v2.1.287 или позже.

Использование MCP prompts как команд

MCP серверы могут предоставлять prompts, которые становятся доступными как команды в Claude Code.

Prompts с сервера с именем anthropic-skills не отображаются, потому что Claude Code зарезервировал это имя для skills, синхронизированных с claude.ai. Инструменты сервера по-прежнему работают. Переименуйте сервер в конфигурации MCP, чтобы отобразить его prompts.

Выполнение MCP prompts

1. Обнаружение доступных prompts

Введите / чтобы увидеть доступные вам команды, включая те, которые поступают с MCP серверов. Claude Code отображает каждый MCP prompt как /servername:promptname (MCP). Ввод /mcp__servername__promptname также запускает его.

2. Выполнение prompt без аргументов

/mcp__github__list_prs

3. Выполнение prompt с аргументами

Многие prompts принимают аргументы. Передавайте их через пробел после команды. Claude Code разделяет аргументы по пробелам, поэтому каждый аргумент — это один токен:

/mcp__github__pr_review 456

/mcp__jira__create_issue login-bug high

[!TIP]

Советы:

• MCP prompts динамически обнаруживаются с подключённых серверов
• Аргументы анализируются на основе определённых параметров prompt
• Результаты prompt вводятся непосредственно в беседу
• В форме /mcp__servername__promptname Claude Code заменяет любой символ в имени сервера вне A-Z, a-z, 0-9, _ и - на _, и использует имя prompt так, как его объявляет сервер

Управляемая конфигурация MCP

Для организаций, которым требуется централизованный контроль над тем, какие серверы MCP могут подключать пользователи, см. Управляемая конфигурация MCP. В ней описывается развертывание фиксированного набора серверов с помощью managed-mcp.json, предоставление серверов каждому пользователю с помощью managedMcpServers, ограничение серверов с помощью allowedMcpServers и deniedMcpServers, а также то, что видят пользователи, когда сервер заблокирован.