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

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.

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

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

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

В сеансе Claude Code выполните:

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

Если Claude Code сообщает, что marketplace не найден, сначала выполните /plugin marketplace add anthropics/claude-plugins-official, а затем повторите попытку установки. После установки выполните /reload-plugins для активации в текущем сеансе.

Запустите skill сборки

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

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

Установка MCP servers

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

Вариант 1: Добавьте удаленный HTTP server

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

# Базовый синтаксис
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 servers через JSON в .mcp.json, ~/.claude.json или claude mcp add-json, поле type принимает streamable-http как псевдоним для http. Спецификация MCP использует имя streamable-http для этого транспорта, поэтому конфигурации, скопированные из документации server, работают без изменений. Запись JSON, которая имеет url, но не имеет type, является ошибкой конфигурации, потому что Claude Code читает запись без type как stdio server. Claude Code пропускает этот server и сообщает MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry. До версии 2.1.202 Claude Code сообщал об этой неправильной конфигурации как command: expected string, received undefined.

Вариант 2: Добавьте удаленный SSE server

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

# Базовый синтаксис
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 server

Stdio servers работают как локальные процессы на вашей машине. Они идеальны для инструментов, которым требуется прямой доступ к системе или пользовательские скрипты. Claude Code устанавливает CLAUDE_PROJECT_DIR в окружение порожденного server в корень проекта, поэтому ваш server может разрешать пути относительно проекта без зависимости от рабочей директории. Это та же директория, которую hooks получают в своей переменной CLAUDE_PROJECT_DIR. Прочитайте ее изнутри вашего процесса server, например process.env.CLAUDE_PROJECT_DIR в Node или os.environ["CLAUDE_PROJECT_DIR"] в Python. CLAUDE_PROJECT_DIR — это стабильный корень проекта и не изменяется при добавлении или удалении рабочих директорий во время сеанса. Server, который ограничивает собственный доступ к файловой системе набором разрешенных директорий, должен вместо этого реализовать MCP запрос roots/list. Claude Code отвечает на roots/list с директорией запуска сеанса плюс каждая дополнительная рабочая директория, которую вы предоставили с помощью --add-dir, /add-dir или параметра additionalDirectories. Claude Code отправляет notifications/roots/list_changed при изменении этого набора. До версии 2.1.203 roots/list возвращал только директорию запуска и Claude Code не отправлял notifications/roots/list_changed. Эта переменная устанавливается в окружение server, а не в собственное окружение Claude Code, поэтому ссылка на нее через расширение ${VAR} в проекте или пользовательском .mcp.json command или args требует значения по умолчанию, такого как ${CLAUDE_PROJECT_DIR:-.}. Конфигурации MCP, предоставляемые плагинами, подставляют ${CLAUDE_PROJECT_DIR} напрямую и не требуют значения по умолчанию.

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

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

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

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 попытался бы разобрать флаги server, такие как --port выше, как свои собственные опции.--env принимает несколько пар KEY=value. Если имя server идет сразу после --env, CLI читает имя как еще одну пару и отклоняет его, поэтому поместите хотя бы одну другую опцию между --env и именем server, как в примерах выше.

Вариант 4: Добавьте удаленный WebSocket server

WebSocket servers поддерживают постоянное двусторонее соединение, которое подходит для удаленных MCP servers, которые отправляют события в Claude без запроса. Используйте HTTP вместо этого, когда ваш server только отвечает на запросы, так как HTTP поддерживает OAuth и флаг claude mcp add --transport, в то время как WebSocket не поддерживает ни то, ни другое. Настройте WebSocket servers в .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.

Управление вашими servers

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

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

# Получить детали для конкретного server
claude mcp get github

# Удалить server
claude mcp remove github

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

Servers с областью действия проекта из .mcp.json, которые ожидают вашего одобрения, отображаются в claude mcp list как ⏸ Pending approval. Запустите claude интерактивно, чтобы просмотреть и одобрить их. claude mcp get <name> показывает ожидающие servers как ⏸ Pending approval и отклоненные servers как ✗ Rejected. Начиная с версии 2.1.196, claude mcp list и claude mcp get читают одобрения .mcp.json только из файлов параметров, которые не проверены в репозитории, пока вы не доверите рабочей области, запустив claude в ней и приняв диалог доверия рабочей области. Клонированный репозиторий не может одобрить свои собственные servers: enableAllProjectMcpServers или enabledMcpjsonServers, зафиксированные в .claude/settings.json проекта, игнорируются в недоверенной папке, и server остается в состоянии ⏸ Pending approval вместо подключения и проверки здоровья. Одобрения из этих источников все еще применяются в недоверенной папке:

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

Одобрения в неотслеживаемом .claude/settings.local.json также применяются, но только после того, как вы примете диалог доверия для этой папки или одной из ее родительских директорий: Claude Code запускает git для проверки того, отслеживается ли файл, и выполняет эту проверку только в доверенной папке. В папке, которой вы никогда не доверяли, одобрения файла ждут диалога доверия, если только папка не является вашей конфигурационной домашней директорией: вашей домашней директорией или директорией, чей .claude вы установили как CLAUDE_CONFIG_DIR. До версии 2.1.207 неотслеживаемый .claude/settings.local.json одобрял servers в папке, которой вы никогда не доверяли. Запись disabledMcpjsonServers в любом файле параметров все еще отклоняет server. Панель /mcp показывает количество инструментов рядом с каждым подключенным server и отмечает servers, которые объявляют возможность tools, но не предоставляют никаких инструментов. Удаленный server, конфигурация которого имеет пустой url, отображается как not configured в /mcp, в claude mcp list и в менеджере /plugin, и Claude Code не пытается подключиться к нему. Плагин может включать запись-заполнитель, подобную этой, для коннектора, который вы настроите позже, поэтому Claude Code не сообщает об этом как об ошибке или проблеме настройки. Представление деталей server в /mcp читает No URL configured for this server; установите url записи для подключения. До версии 2.1.208 Claude Code сообщал об пустом url как о проблеме конфигурации с подсказкой переподключиться. Если ваш запрос требует инструментов от server, который все еще подключается в фоновом режиме, Claude ждет подключения этого server перед продолжением. С включенным поиском инструментов, который используется по умолчанию, ожидание происходит внутри вызова ToolSearch. В конфигурациях без поиска инструментов, таких как Google Cloud’s Agent Platform, пользовательский ANTHROPIC_BASE_URL или ENABLE_TOOL_SEARCH=false, Claude использует инструмент WaitForMcpServers вместо этого. Некоторые имена servers зарезервированы для встроенных servers Claude Code: workspace, claude-in-chrome, computer-use, Claude Preview и Claude Browser. Если ваша конфигурация определяет server с зарезервированным именем, Claude Code пропускает его при загрузке и показывает предупреждение с просьбой переименовать его. claude mcp add отклоняет зарезервированное имя с ошибкой. Claude Preview и Claude Browser оба называют встроенный server, который использует панель предпросмотра приложения Claude Code desktop. До версии 2.1.205 Claude Browser не был зарезервирован, поэтому пользовательский server мог зарегистрироваться под этим именем.

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

Claude Code поддерживает MCP list_changed уведомления, позволяя MCP servers динамически обновлять свои доступные инструменты, подсказки и ресурсы без необходимости отключения и переподключения. Когда MCP server отправляет уведомление list_changed, Claude Code автоматически обновляет доступные возможности от этого server.

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

Если HTTP или SSE server отключится во время сеанса, Claude Code автоматически переподключится с экспоненциальной задержкой: до пяти попыток, начиная с задержки в одну секунду и удваивая каждый раз. Server отображается как ожидающий в /mcp во время переподключения. После пяти неудачных попыток server помечается как неудачный, и вы можете повторить попытку вручную из /mcp. Stdio servers — это локальные процессы и не переподключаются автоматически. Та же задержка применяется, когда HTTP или SSE server не может подключиться при запуске. Начиная с версии 2.1.121, Claude Code повторяет попытку начального подключения до трех раз при временных ошибках, таких как ответ 5xx, отказ в соединении или timeout, а затем помечает server как неудачный, если он все еще не может подключиться. Ошибки аутентификации и ошибки не найдено не повторяются, так как они требуют изменения конфигурации для разрешения. Когда настроенный server не может подключиться, Claude Code сообщает Claude, какой server не удалось подключить и его ошибку подключения, включая результаты ToolSearch, которые не находят соответствующий инструмент, поэтому Claude сообщает об ошибке подключения в своем ответе. Требуется поиск инструментов, который включен по умолчанию. В конфигурациях без поиска инструментов, таких как пользовательский ANTHROPIC_BASE_URL, ENABLE_TOOL_SEARCH=false или модель, которая не поддерживает поиск инструментов, а также на Amazon Bedrock, Google Cloud’s Agent Platform и Microsoft Foundry, Claude Code не сообщает Claude об ошибках подключения неудачных servers. До версии 2.1.205 Claude Code не передавал ошибки подключения Claude, и Claude мог ответить так, как будто инструменты неудачного server никогда не были настроены. Начиная с версии 2.1.191, запросы обнаружения возможностей, которые выполняются после успешного подключения, такие как tools/list, prompts/list и resources/list, также повторяют временные сетевые и серверные ошибки до трех раз с короткой задержкой. Ошибки аутентификации, ответы 4xx и timeout запросов не повторяются.

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

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

Советы:

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

Timeout для каждого server — это жесткий лимит реального времени для каждого вызова инструмента, и уведомления о прогрессе от server не продлевают его. Значения ниже 1000 игнорируются и переходят к MCP_TOOL_TIMEOUT, или к его значению по умолчанию примерно 28 часов, когда эта переменная не установлена. Для HTTP, SSE или claude.ai connector server существует также второй таймер для каждого запроса, который охватывает каждый запрос до первого байта ответа server. Этот таймер составляет 60 секунд, если вы не установите timeout для каждого server или MCP_TOOL_TIMEOUT; установка любого из них на 60 секунд или выше повышает таймер для каждого запроса до этого значения, более низкое значение не сокращает его, и значение по умолчанию 28 часов неустановленного MCP_TOOL_TIMEOUT никогда не питает его. Stdio и WebSocket servers не имеют таймера для каждого запроса. До версии 2.1.162 значения ниже 1000 округлялись до одной секунды вместо этого. Timeout для каждого server не менее 1000 также действует как нижний предел для timeout неактивности, описанного ниже: Claude Code никогда не прерывает вызовы инструментов этого server из-за неактивности раньше, чем timeout для каждого server. Требуется Claude Code версии 2.1.203 или позже. Вызов инструмента к MCP server, который не отправляет ответ и не отправляет уведомление о прогрессе в течение окна неактивности, прерывается с ошибкой вместо ожидания лимита реального времени. Timeout неактивности требует Claude Code версии 2.1.187 или позже. Он применяется к каждому типу server, кроме IDE servers и SDK in-process servers. Окно неактивности по умолчанию составляет пять минут для HTTP, SSE, WebSocket и claude.ai connector servers, и 30 минут для stdio servers. До версии 2.1.203 stdio servers были освобождены от timeout неактивности. Установите переменную окружения CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT в миллисекундах, чтобы изменить окно неактивности, или установите ее на 0, чтобы отключить проверку.

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

Плагины могут включать MCP servers, автоматически предоставляя инструменты и интеграции при включении плагина. Plugin MCP servers работают идентично пользовательским настроенным servers. Как работают plugin MCP servers:

Плагины определяют MCP servers в .mcp.json в корне плагина или встроенные в plugin.json
Когда плагин включен, его MCP servers запускаются автоматически
Plugin MCP tools отображаются рядом с вручную настроенными MCP tools
Plugin servers управляются через установку плагина, не через команды /mcp

Пример конфигурации plugin 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"]
    }
  }
}

Функции plugin MCP:

Автоматический жизненный цикл: При запуске сеанса servers для включенных плагинов подключаются автоматически. Если вы включите или отключите плагин во время сеанса, запустите /reload-plugins для подключения или отключения его MCP servers
Переменные пути: ${CLAUDE_PLUGIN_ROOT} разрешается в директорию установки плагина, ${CLAUDE_PLUGIN_DATA} в его директорию постоянного состояния, и ${CLAUDE_PROJECT_DIR} в стабильный корень проекта. Подстановка применяется к:
- stdio servers: command, args, env
- http, sse и ws servers: url, headers и headersHelper. До версии 2.1.195 headersHelper передавал заполнитель как буквальную строку
Доступ к переменным окружения пользователя: доступ к тем же переменным окружения, что и вручную настроенные servers
Несколько типов транспорта: поддержка stdio, SSE, HTTP и WebSocket транспортов, хотя поддержка транспорта может варьироваться в зависимости от server

Просмотр plugin MCP servers:

# В Claude Code, см. все MCP servers, включая plugin ones
/mcp

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

mcp__plugin_my-plugin_database-tools__query

Используйте это полное имя при ссылке на инструмент в правилах разрешений, в списке allowed-tools skill, в поле tools subagent или в matcher hook. Matcher hook, написанный для простого ключа server, такой как mcp__database-tools__.*, никогда не срабатывает для plugin-bundled server. Server сам регистрируется под scoped именем plugin:<plugin-name>:<server-name>, такой как plugin:my-plugin:database-tools. Используйте это имя там, где ожидается имя настроенного server, такой как поле server hook mcp_tool. Преимущества plugin MCP servers:

Упакованное распределение: инструменты и servers упакованы вместе
Автоматическая настройка: не требуется ручная конфигурация MCP
Согласованность команды: все получают одинаковые инструменты при установке плагина

См. справочник компонентов плагина для получения подробной информации о включении MCP servers в плагины.

Области установки MCP

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

Область	Загружается в	Общий доступ с командой	Хранится в
Локальная	Только текущий проект	Нет	`~/.claude.json`
Проект	Только текущий проект	Да, через контроль версий	`.mcp.json` в корне проекта
Пользователь	Все ваши проекты	Нет	`~/.claude.json`

Локальная область

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

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

# Добавить server с локальной областью (по умолчанию)
claude mcp add --transport http stripe https://mcp.stripe.com

# Явно указать локальную область
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

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

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

Область проекта

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

# Добавить server с областью проекта
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

Результирующий файл .mcp.json следует стандартизированному формату:

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

По соображениям безопасности Claude Code запрашивает одобрение перед использованием servers с областью проекта из файлов .mcp.json. Если вам нужно сбросить эти выборы одобрения, используйте команду claude mcp reset-project-choices.

Область пользователя

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

# Добавить server пользователя
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

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

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

Локальная область
Область проекта
Область пользователя
Plugin-provided servers
claude.ai connectors

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

Расширение переменных окружения в `.mcp.json`

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

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

Места расширения: Переменные окружения могут быть расширены в:

command - путь к исполняемому файлу server
args - аргументы командной строки
env - переменные окружения, передаваемые server
url - для типов HTTP server
headers - для аутентификации HTTP server

Пример с расширением переменных:

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

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

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

Пример: мониторинг ошибок с помощью Sentry

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

Аутентифицируйтесь с помощью вашей учетной записи Sentry:

/mcp

Затем отладьте проблемы в production:

Какие наиболее распространенные ошибки за последние 24 часа?

Покажите мне трассировку стека для ошибки ID abc123

Какое развертывание внесло эти новые ошибки?

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

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

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

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

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

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

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

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

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

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

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

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

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

Аутентификация с удаленными MCP servers

Многие облачные MCP servers требуют аутентификации. Claude Code поддерживает OAuth 2.0 для безопасных соединений. Claude Code отмечает удаленный server как требующий аутентификации, когда server отвечает с 401 Unauthorized или 403 Forbidden. Для server, на который вы еще не вошли, любой из этих кодов состояния отмечает его в /mcp, чтобы вы могли завершить поток OAuth. Когда запрос к OAuth server, на который вы уже вошли, возвращает 401 Unauthorized, Claude Code обновляет сохраненный токен, переподключается и повторяет запрос один раз. Он отмечает server в /mcp только если этот повторный запрос также не удается. До v2.1.206 обновление токена, которое не удалось по временной причине, такой как ошибка сети, отмечало OAuth server как требующий аутентификации для остальной части сеанса, даже если его токен обновления был все еще действителен. Начиная с v2.1.195, когда обновление токена не удается, потому что server отклоняет сохраненный токен обновления, Claude Code немедленно показывает уведомление, указывающее на /mcp. Меню подключенного server там предлагает Re-authenticate, чтобы вы могли снова войти перед следующим вызовом инструмента. Пользовательский server, который возвращает заголовок WWW-Authenticate, указывающий на его сервер авторизации, получает то же автоматическое обнаружение, как и любой другой удаленный server. Начиная с v2.1.193, Claude Code также показывает уведомление при запуске, когда один или несколько настроенных servers требуют аутентификации, поэтому вам не нужно открывать /mcp для обнаружения, какие servers требуют входа. В неинтерактивном режиме нет панели /mcp, поэтому Claude Code не может запустить поток OAuth для вас. Начиная с v2.1.196, когда настроенный server требует аутентификации во время запуска claude -p или Agent SDK с включенным поиском инструментов, что является значением по умолчанию, Claude Code сообщает Claude, что инструменты server недоступны, пока вы его не авторизуете. Claude затем может назвать server, который требует входа, вместо того чтобы отвечать так, как будто server не был настроен. Завершите вход из интерактивного сеанса с помощью /mcp или claude mcp login <name>. Если вы настроили headers.Authorization для server и server отклонил этот заголовок, Claude Code сообщает о соединении как о неудачном вместо того, чтобы вернуться к OAuth. Проверьте, что токен действителен для конечной точки MCP, или удалите заголовок, чтобы использовать поток OAuth.

Добавьте server, который требует аутентификации

Например:

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

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

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

/mcp

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

Советы:

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

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

Начиная с v2.1.186, claude mcp login <name> запускает поток OAuth настроенного server прямо из вашей оболочки, поэтому вам не нужно открывать панель /mcp внутри сеанса.

claude mcp login sentry

Чтобы позже очистить сохраненные учетные данные, запустите claude mcp logout <name>. Начиная с v2.1.191, команда обнаруживает, когда локальный браузер недоступен, например во время сеанса SSH или на Linux без сервера отображения, и выводит URL авторизации вместо попытки открыть браузер. Откройте URL на вашей локальной машине, затем вставьте полный URL перенаправления из адресной строки браузера обратно в приглашение. Команде требуется интерактивный терминал для шага вставки, поэтому подключитесь с помощью ssh -t. Передайте --no-browser для принудительного приглашения URL даже при обнаружении локального браузера.

claude mcp login sentry --no-browser

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

Некоторые MCP servers требуют конкретный URI перенаправления, зарегистрированный заранее. По умолчанию Claude Code выбирает случайный доступный порт для обратного вызова OAuth. Используйте --callback-port для фиксации порта, чтобы он соответствовал предварительно зарегистрированному URI перенаправления формы http://localhost:PORT/callback. Вы можете использовать --callback-port самостоятельно (с динамической регистрацией клиента) или вместе с --client-id (с предварительно настроенными учетными данными).

# Фиксированный порт обратного вызова с динамической регистрацией клиента
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

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

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

Зарегистрируйте приложение OAuth с помощью server

Создайте приложение через портал разработчика server и запишите ваш client ID и client secret.Многие servers также требуют URI перенаправления. Если это так, выберите порт и зарегистрируйте URI перенаправления в формате http://localhost:PORT/callback. Используйте тот же порт с --callback-port на следующем шаге.

Добавьте server с вашими учетными данными

Выберите один из следующих методов. Порт, используемый для --callback-port, может быть любым доступным портом. Он просто должен соответствовать URI перенаправления, который вы зарегистрировали на предыдущем шаге.

claude mcp add
claude mcp add-json
claude mcp add-json (только порт обратного вызова)
CI / переменная окружения

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

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

Включите объект 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

Используйте --callback-port без client ID для фиксации порта при использовании динамической регистрации клиента:

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

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

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

Аутентифицируйтесь в Claude Code

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

Советы:

Client secret хранится безопасно в вашей системной связке ключей (macOS) или файле учетных данных, а не в вашей конфигурации
Если server использует публичный OAuth клиент без secret, используйте только --client-id без --client-secret
--callback-port можно использовать с --client-id или без него
Эти флаги применяются только к HTTP и SSE транспортам. Они не влияют на stdio servers
Используйте claude mcp get <name> для проверки того, что учетные данные OAuth настроены для server

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

Укажите Claude Code на конкретный URL метаданных сервера авторизации OAuth, чтобы обойти цепочку обнаружения по умолчанию. Установите authServerMetadataUrl, когда стандартные конечные точки MCP server выдают ошибку, или когда вы хотите направить обнаружение через внутренний прокси. По умолчанию Claude Code сначала проверяет метаданные защищенного ресурса RFC 9728 на /.well-known/oauth-protected-resource, затем возвращается к метаданным сервера авторизации RFC 8414 на /.well-known/oauth-authorization-server. Установите authServerMetadataUrl в объекте oauth конфигурации вашего server в .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 метаданных переопределяет области, которые объявляет upstream server.

Ограничьте области OAuth

Установите oauth.scopes для фиксации областей, которые Claude Code запрашивает во время потока авторизации. Это поддерживаемый способ ограничить MCP server подмножеством, одобренным командой безопасности, когда upstream сервер авторизации объявляет больше областей, чем вы хотите предоставить. Значение — это одна строка, разделенная пробелами, соответствующая формату параметра 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 и областями, которые server обнаруживает на /.well-known. Оставьте его неустановленным, чтобы позволить MCP server определить запрашиваемый набор областей. Начиная с v2.1.196, когда oauth.scopes не установлен, Claude Code запрашивает область, предоставленную заголовком WWW-Authenticate server или его метаданными защищенного ресурса, и не отправляет параметр scope, когда ни один из них не предоставляет его. Он больше не запрашивает полный каталог scopes_supported из автоматически обнаруженных метаданных сервера авторизации. Запрос этого каталога заставил поставщиков идентификации, которые объявляют области только для администраторов или шаблонов, отклонить запрос авторизации с ошибкой invalid_scope. Метаданные, полученные из настроенного authServerMetadataUrl, по-прежнему предоставляют свой scopes_supported как запрашиваемые области. Если сервер авторизации объявляет offline_access в scopes_supported, Claude Code добавляет его к фиксированным областям, чтобы токен доступа мог быть обновлен без нового входа в браузер. Если server позже возвращает 403 insufficient_scope для вызова инструмента, Claude Code переаутентифицируется с теми же фиксированными областями. Расширьте oauth.scopes, когда инструмент, который вам нужен, требует область вне фиксации.

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

Если ваш MCP server использует схему аутентификации, отличную от 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)\"'\"}'"
    }
  }
}

Требования:

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

Помощник запускается заново при каждом подключении (при запуске сеанса и при переподключении). Кэширования нет, поэтому ваш скрипт отвечает за любое повторное использование токена. Начиная с v2.1.193, если вызов инструмента возвращает 401 Unauthorized или 403 Forbidden, Claude Code автоматически повторно запускает помощника, переподключается со свежими заголовками и повторяет вызов один раз. Claude Code отмечает server как требующий аутентификации в /mcp только если этот повторный вызов также не удается. Claude Code устанавливает эти переменные окружения при выполнении помощника:

Переменная	Значение
`CLAUDE_CODE_MCP_SERVER_NAME`	имя MCP server
`CLAUDE_CODE_MCP_SERVER_URL`	URL MCP server
`CLAUDE_PLUGIN_ROOT`	корневой каталог плагина. Установлено только когда плагин предоставляет server

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

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

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

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

Добавьте 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

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

claude mcp get weather-api

Советы:

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

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

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

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

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

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

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

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

claude mcp list

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

Советы:

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

Используйте MCP servers из claude.ai

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

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

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

Аутентифицируйте MCP server

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

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

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

/mcp

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

Начиная с версии 2.1.161, коннекторы, в которые вы никогда не входили, свернуты за строкой Show unused connectors в конце раздела claude.ai, поэтому список, предоставленный организацией, не заполняет панель. Выберите строку, чтобы развернуть их. Коннектор, в который вы входили ранее, остается видимым даже если в настоящее время требуется повторная аутентификация. Коннекторы из claude.ai загружаются только когда ваш активный метод аутентификации — это ваша подписка claude.ai. Они не загружаются, когда активны ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, apiKeyHelper или сторонний поставщик, такой как Amazon Bedrock или Google Cloud’s Agent Platform, даже если вы ранее запустили /login. Если /mcp не отображает коннектор, который вы добавили, запустите /status, чтобы подтвердить, какой метод аутентификации активен, отмените установку этой переменной окружения или удалите параметр apiKeyHelper, затем запустите /login, чтобы выбрать вашу учетную запись claude.ai. Server, который вы добавили в Claude Code, имеет приоритет над коннектором claude.ai, который указывает на тот же URL. Когда это происходит, /mcp отображает коннектор как скрытый и показывает, как удалить дубликат, если вы предпочитаете использовать коннектор. Некоторые размещенные Anthropic коннекторы, такие как Microsoft 365, Gmail и Google Calendar, не поддерживают локальный OAuth из Claude Code, потому что поставщик идентификации вышестоящего уровня принимает только URL перенаправления, который зарегистрировала claude.ai. Начиная с версии 2.1.162, аутентификация одного из этих хостов в /mcp показывает сообщение, направляющее вас подключить его в Settings → Connectors на claude.ai. После подключения там коннектор автоматически появляется в Claude Code.

Управление инструментами connector организацией

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

Инструмент установлен на ask: Claude Code запрашивает при каждом вызове с причиной Your organization requires approval for this tool. Запрос появляется даже в режимах acceptEdits, auto и bypassPermissions permission modes, и никогда не предлагает опцию запомнить ваш выбор. Allow rules, которые соответствуют инструменту, также не пропускают запрос. В режиме dontAsk, который никогда не запрашивает, Claude Code вместо этого отклоняет вызов.
Инструмент установлен на blocked: Claude Code фильтрует инструмент перед тем, как Claude его увидит, поэтому он никогда не появляется в списке инструментов.

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

Отключите коннекторы claude.ai

Чтобы отключить MCP servers claude.ai в Claude Code, установите disableClaudeAiConnectors на true в любой области параметров:

{
  "disableClaudeAiConnectors": true
}

Этот параметр использует семантику any-source-true: true в любом источнике параметров имеет приоритет. Проверенный в репозитории файл .claude/settings.json может исключить репозиторий из облачных коннекторов, но параметр false на уровне проекта не может повторно включить коннекторы, которые параметр true на уровне пользователя или политики отключил. Servers, переданные явно через --mcp-config, не затронуты. Вы также можете установить переменную окружения ENABLE_CLAUDEAI_MCP_SERVERS на false, которая имеет тот же эффект для текущего сеанса оболочки:

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

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

Эти параметры на стороне клиента управляют локальными сеансами Claude Code. В сеансах Claude Code в веб-версии коннекторы claude.ai предоставляются удаленным хостом и поступают как явные записи --mcp-config, поэтому disableClaudeAiConnectors не применяется там. URL коннекторов также переписываются через прокси сеанса, поэтому шаблон serverUrl в deniedMcpServers, нацеленный на URL поставщика, не будет совпадать. Управляйте тем, какие коннекторы может использовать облачный сеанс, из параметров организации claude.ai.

Используйте Claude Code как MCP server

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

# Запустите Claude как stdio MCP server
claude mcp serve

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

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

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

which claude

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

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

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

Советы:

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

Лимиты выхода 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

Чтобы увеличить лимит для инструментов, которые производят большие выходы:

export MAX_MCP_OUTPUT_TOKENS=50000
claude

Это особенно полезно при работе с MCP servers, которые:

запрашивают большие наборы данных или базы данных
генерируют подробные отчеты или документацию
обрабатывают обширные файлы журналов или информацию отладки

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

Если вы создаете MCP server, вы можете позволить отдельным инструментам возвращать результаты больше, чем порог сохранения на диск по умолчанию, установив _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 servers, которые вы не контролируете, рассмотрите возможность увеличения лимита MAX_MCP_OUTPUT_TOKENS. Вы также можете попросить автора server добавить аннотацию anthropic/maxResultSizeChars или разбить на страницы свои ответы. Аннотация не влияет на инструменты, которые возвращают содержимое изображения; для них повышение MAX_MCP_OUTPUT_TOKENS — единственный вариант.

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

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

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

Ваш server получает любые аргументы, которые выбрал Claude, поэтому продолжайте проверять комбинацию на стороне server. Когда Claude Code не может создать схему, которую API принимает, или при развертывании, которое не получает удаленную конфигурацию, которая включает переписывание, такую как автономная машина, он пропускает этот один инструмент, записывает причину в журнал server и оставляет другие инструменты server доступными. Версии ранее, чем v2.1.195, пропускают каждый инструмент, чья схема ввода имеет корневой anyOf, oneOf или allOf.

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

Если вы создаете MCP server, вы можете отметить инструмент как требующий явного одобрения при каждом вызове, установив _meta["anthropic/requiresUserInteraction"] на true в записи инструмента в ответе tools/list. Значение должно быть логическим JSON true; любое другое значение игнорируется. Claude Code показывает приглашение разрешения этого инструмента при каждом вызове, даже в режимах разрешений acceptEdits, auto и bypassPermissions (/ru/permissions#permission-modes), и не предлагает опцию “не спрашивать снова” для него. Правила разрешения, которые совпадают с инструментом, также не пропускают приглашение. В режиме dontAsk, который никогда не запрашивает, Claude Code отклоняет вызов вместо этого. Приглашение должно достичь человека. В неинтерактивном режиме с --permission-prompt-tool, результат allow из инструмента приглашения для отмеченного инструмента преобразуется в отказ с сообщением MCP tool requires user interaction; not supported via --permission-prompt-tool. Обратный вызов canUseTool Agent SDK получает эти вызовы и может их одобрить, потому что ожидается, что хост SDK покажет их пользователю. Используйте это для инструментов, чье приглашение разрешения само по себе является целью, такие как шаг согласия или предоставления доступа, где автоматическое одобрение означало бы, что ни один человек никогда не согласился. Другие инструменты из того же server сохраняют свое нормальное поведение разрешения. Следующая запись tools/list отмечает один инструмент как всегда требующий одобрения.

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

Аннотация anthropic/requiresUserInteraction требует Claude Code v2.1.199 или позже. Более ранние версии игнорируют ее и применяют стандартный поток разрешения. Когда сеанс подключен к Remote Control или хосту SDK, Claude Code отмечает запрос разрешения как требующий взаимодействия пользователя, поэтому клиент показывает приглашение разрешения инструмента для вас, чтобы ответить, вместо действия одобрения одним касанием.

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

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

Режим формы: Claude Code показывает диалог с полями формы, определенными server (например, приглашение имени пользователя и пароля). Заполните поля и отправьте.
Режим URL: Claude Code открывает URL браузера для аутентификации или одобрения. Завершите процесс в браузере, затем подтвердите в CLI.

Чтобы автоматически ответить на запросы elicitation без отображения диалога, используйте Elicitation hook. Если вы создаете MCP server, который использует elicitation, см. спецификацию MCP elicitation для деталей протокола и примеров схемы.

Используйте MCP ресурсы

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

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

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

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

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

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

Можете ли вы проанализировать @github:issue://123 и предложить исправление?

Пожалуйста, проверьте документацию API на @docs:file://api/authentication

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

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

Сравните @postgres:schema://users с @docs:file://database/user-model

Советы:

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

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

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

Как это работает

Tool search включен по умолчанию. Инструменты MCP откладываются, а не загружаются в контекст заранее, и Claude использует инструмент поиска для обнаружения релевантных инструментов, когда задача их требует. Только инструменты, которые Claude действительно использует, входят в контекст. С вашей точки зрения инструменты MCP работают точно так же, как раньше. Если вы предпочитаете загрузку на основе порога, установите ENABLE_TOOL_SEARCH=auto для загрузки схем заранее, когда они подходят в пределах 10% окна контекста, и откладывайте только переполнение. См. Настройте tool search для всех опций.

Для авторов MCP server

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

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

Claude Code усекает описания инструментов и инструкции server на 2KB каждое. Держите их краткими, чтобы избежать усечения, и поместите критические детали в начало.

Настройте tool search

Tool search включен по умолчанию: инструменты MCP откладываются и обнаруживаются по требованию. Claude Code отключает его по умолчанию на Google Cloud’s Agent Platform. Он также отключен, когда ANTHROPIC_BASE_URL указывает на хост, не являющийся первой стороной, так как большинство прокси не пересылают блоки tool_reference. Установите ENABLE_TOOL_SEARCH явно, чтобы переопределить любой резервный вариант. Установка CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS сохраняет tool search отключенным, и ENABLE_TOOL_SEARCH не может его переопределить. Переменная удаляет заголовок бета-версии, который требуют определения инструментов defer_loading и блоки содержимого tool_reference. Tool search требует модель, которая поддерживает блоки tool_reference: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 и более поздние модели. См. совместимость моделей в документации API для текущего списка. На Google Cloud’s Agent Platform tool search поддерживается для Claude Sonnet 4.5 и позже и Claude Opus 4.5 и позже. Управляйте поведением tool search с помощью переменной окружения ENABLE_TOOL_SEARCH:

Значение	Поведение
(не установлено)	Все инструменты MCP откладываются и загружаются по требованию. Возвращается к загрузке заранее на Google Cloud’s Agent Platform или когда `ANTHROPIC_BASE_URL` является хостом, не являющимся первой стороной
`true`	Все инструменты MCP откладываются. Claude Code отправляет заголовок бета-версии даже на Google Cloud’s Agent Platform и через прокси. Запросы завершаются ошибкой на моделях Google Cloud’s Agent Platform ранее, чем Sonnet 4.5 или Opus 4.5, или на прокси, которые не поддерживают блоки `tool_reference`
`auto`	Режим порога: инструменты загружаются заранее, если они подходят в пределах 10% окна контекста, откладываются иначе
`auto:N`	Режим порога с пользовательским процентом, где `N` — это 0-100. Например, `auto:5` для 5%
`false`	Все инструменты MCP загружаются заранее, без откладывания

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

# Полностью отключите tool search
ENABLE_TOOL_SEARCH=false claude

Или установите значение в поле env вашего settings.json. Вы также можете отключить инструмент ToolSearch специально:

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

Исключите server из откладывания

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

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

Поле alwaysLoad доступно на всех типах server и требует Claude Code v2.1.121 или позже. MCP server также может отметить отдельные инструменты как всегда загружаемые, включив "anthropic/alwaysLoad": true в объект _meta инструмента, что имеет тот же эффект только для этого инструмента. Установка alwaysLoad: true также блокирует запуск до подключения server, ограничено стандартным тайм-аутом подключения в 5 секунд. Это применяется даже когда MCP startup является неблокирующим по умолчанию, так как инструменты должны присутствовать при построении первого приглашения. Другие servers продолжают подключаться в фоновом режиме.

Используйте MCP подсказки как команды

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

Выполните MCP подсказки

Откройте доступные подсказки

Введите / для просмотра всех доступных команд, включая те из MCP servers. MCP подсказки отображаются в формате /mcp__servername__promptname.

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

/mcp__github__list_prs

Выполните подсказку с аргументами

Многие подсказки принимают аргументы. Передайте их через пробел после команды:

/mcp__github__pr_review 456

/mcp__jira__create_issue "Bug in login flow" high

Советы:

MCP подсказки динамически обнаруживаются из подключенных servers
Аргументы анализируются на основе определенных параметров подсказки
Результаты подсказки вводятся непосредственно в разговор
Имена server и подсказки нормализуются (пробелы становятся подчеркиваниями)

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

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

⌘I

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

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

​Установка MCP servers

​Вариант 1: Добавьте удаленный HTTP server

​Вариант 2: Добавьте удаленный SSE server

​Вариант 3: Добавьте локальный stdio server

​Вариант 4: Добавьте удаленный WebSocket server

​Управление вашими servers

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

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

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

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

​Области установки MCP

​Локальная область

​Область проекта

​Область пользователя

​Иерархия области и приоритет

​Расширение переменных окружения в .mcp.json

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

​Пример: мониторинг ошибок с помощью Sentry

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

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

​Аутентификация с удаленными MCP servers

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

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

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

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

​Ограничьте области OAuth

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

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

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

​Используйте MCP servers из claude.ai

​Управление инструментами connector организацией

​Отключите коннекторы claude.ai

​Используйте Claude Code как MCP server

​Лимиты выхода MCP и предупреждения

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

​Инструменты с корневым комбинатором в схеме ввода

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

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

​Используйте MCP ресурсы

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

​Масштабирование с помощью MCP Tool Search

​Как это работает

​Для авторов MCP server

​Настройте tool search

​Исключите server из откладывания

​Используйте MCP подсказки как команды

​Выполните MCP подсказки

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

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

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

Установка MCP servers

Вариант 1: Добавьте удаленный HTTP server

Вариант 2: Добавьте удаленный SSE server

Вариант 3: Добавьте локальный stdio server

Вариант 4: Добавьте удаленный WebSocket server

Управление вашими servers

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

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

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

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

Области установки MCP

Локальная область

Область проекта

Область пользователя

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

Расширение переменных окружения в `.mcp.json`

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

Пример: мониторинг ошибок с помощью Sentry

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

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

Аутентификация с удаленными MCP servers

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

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

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

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

Ограничьте области OAuth

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

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

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

Используйте MCP servers из claude.ai

Управление инструментами connector организацией

Отключите коннекторы claude.ai

Используйте Claude Code как MCP server

Лимиты выхода MCP и предупреждения

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

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

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

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

Используйте MCP ресурсы

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

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

Как это работает

Для авторов MCP server

Настройте tool search

Исключите server из откладывания

Используйте MCP подсказки как команды

Выполните MCP подсказки

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