Подключите 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.
Чтобы создать свой собственный 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, работают без изменений.
Вариант 2: Добавьте удаленный SSE server
# Базовый синтаксис
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. Ваш server также может вызвать MCP запрос roots/list, который возвращает директорию, из которой был запущен Claude Code.
Эта переменная устанавливается в окружение 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
Вариант 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.
Панель /mcp показывает количество инструментов рядом с каждым подключенным server и отмечает servers, которые объявляют возможность tools, но не предоставляют никаких инструментов.
Если ваш запрос требует инструментов от server, который все еще подключается в фоновом режиме, Claude ждет подключения этого server перед продолжением. С включенным поиском инструментов, который используется по умолчанию, ожидание происходит внутри вызова ToolSearch. В конфигурациях без поиска инструментов, таких как Vertex AI, пользовательский ANTHROPIC_BASE_URL или ENABLE_TOOL_SEARCH=false, Claude использует инструмент WaitForMcpServers вместо этого.
Имя server workspace зарезервировано для внутреннего использования. Если ваша конфигурация определяет server с этим именем, Claude Code пропускает его при загрузке и показывает предупреждение с просьбой переименовать его.
Динамические обновления инструментов
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 как неудачный, если он все еще не может подключиться. Ошибки аутентификации и ошибки не найдено не повторяются, так как они требуют изменения конфигурации для разрешения.
Отправка сообщений через каналы
MCP server также может отправлять сообщения непосредственно в вашу сессию, чтобы Claude мог реагировать на внешние события, такие как результаты CI, оповещения мониторинга или сообщения чата. Чтобы включить это, ваш server объявляет возможность claude/channel и вы включаете ее с флагом --channels при запуске. См. Каналы для использования официально поддерживаемого канала или Справочник каналов для создания собственного.
Timeout для каждого server — это жесткий лимит реального времени для каждого вызова инструмента, и уведомления о прогрессе от server не продлевают его. Значения ниже 1000 игнорируются и переходят к MCP_TOOL_TIMEOUT, или к его значению по умолчанию примерно 28 часов, когда эта переменная не установлена. {/* min-version: 2.1.162 */}До версии 2.1.162 значения ниже 1000 округлялись до одной секунды. Для HTTP и SSE servers бюджет первого байта для каждого запроса fetch имеет минимум 60 секунд.
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}для стабильного корня проекта - Доступ к переменным окружения пользователя: доступ к тем же переменным окружения, что и вручную настроенные 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.
Преимущества 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 с учетными данными, которые вы не хотите в контроле версий.
# Добавить 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- путь к исполняемому файлу serverargs- аргументы командной строкиenv- переменные окружения, передаваемые serverurl- для типов HTTP serverheaders- для аутентификации HTTP server
Пример с расширением переменных:
{
"mcpServers": {
"api-server": {
"type": "http",
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
"headers": {
"Authorization": "Bearer ${API_KEY}"
}
}
}
}
Если требуемая переменная окружения не установлена и не имеет значения по умолчанию, Claude Code не сможет разобрать конфигурацию.
Практические примеры
Пример: мониторинг ошибок с помощью 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. Пользовательский server, который возвращает заголовок WWW-Authenticate, указывающий на его сервер авторизации, получает то же автоматическое обнаружение, как и любой другой удаленный server.
Если вы настроили 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
Затем следуйте инструкциям в вашем браузере для входа.
Используйте фиксированный порт обратного вызова 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 перенаправления, который вы зарегистрировали на предыдущем шаге.
Используйте --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 и следуйте потоку входа браузера.
Переопределите обнаружение метаданных 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://. authServerMetadataUrl требует Claude Code v2.1.64 или позже. 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 определить запрашиваемый набор областей.
Если сервер авторизации объявляет 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 секунд
- Динамические заголовки переопределяют любые статические
headersс тем же именем
Помощник запускается заново при каждом подключении (при запуске сеанса и при переподключении). Кэширования нет, поэтому ваш скрипт отвечает за любое повторное использование токена.
Claude Code устанавливает эти переменные окружения при выполнении помощника:
| Переменная | Значение |
|---|---|
CLAUDE_CODE_MCP_SERVER_NAME |
имя MCP server |
CLAUDE_CODE_MCP_SERVER_URL |
URL MCP server |
Используйте их для написания одного скрипта помощника, который служит нескольким MCP servers.
Добавьте 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
Импортируйте MCP servers из Claude Desktop
Если вы уже настроили MCP servers в Claude Desktop, вы можете их импортировать:
Импортируйте servers из Claude Desktop
# Базовый синтаксис
claude mcp add-from-claude-desktop
Выберите, какие servers импортировать
После запуска команды вы увидите интерактивный диалог, который позволяет вам выбрать, какие servers вы хотите импортировать.
Проверьте, что servers были импортированы
claude mcp list
Используйте MCP servers из Claude.ai
Если вы вошли в Claude Code с учетной записью Claude.ai, MCP servers, которые вы добавили в Claude.ai, автоматически доступны в Claude Code:
Настройте MCP servers в Claude.ai
Добавьте servers на claude.ai/customize/connectors. В планах Team и Enterprise только администраторы могут добавлять servers.
Аутентифицируйте MCP server
Завершите все необходимые шаги аутентификации в Claude.ai.
Просмотрите и управляйте servers в Claude Code
В Claude Code используйте команду:
/mcp
Claude.ai servers отображаются в списке с индикаторами, показывающими, что они поступают из Claude.ai.
Начиная с версии 2.1.161, коннекторы, в которые вы никогда не входили, свернуты за строкой Show unused connectors в конце раздела claude.ai, поэтому список, предоставленный организацией, не заполняет панель. Выберите строку, чтобы развернуть их. Коннектор, в который вы входили ранее, остается видимым даже если в настоящее время требуется повторная аутентификация.
Коннекторы Claude.ai загружаются только когда ваш активный метод аутентификации — это ваша подписка Claude.ai. Они не загружаются, когда активны ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, apiKeyHelper или сторонний поставщик, такой как Bedrock или Vertex, даже если вы ранее запустили /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.
Чтобы отключить MCP servers claude.ai в Claude Code, установите переменную окружения ENABLE_CLAUDEAI_MCP_SERVERS на false:
ENABLE_CLAUDEAI_MCP_SERVERS=false claude
Используйте 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": {}
}
}
}
Лимиты выхода 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 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
Масштабирование с помощью 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 отключает его по умолчанию на Vertex AI. Он также отключен, когда ANTHROPIC_BASE_URL указывает на хост, не являющийся первой стороной, так как большинство прокси не пересылают блоки tool_reference. Установите ENABLE_TOOL_SEARCH явно, чтобы переопределить любой резервный вариант.
Tool search требует модель, которая поддерживает блоки tool_reference. Модели Haiku не поддерживают это. На Vertex AI tool search поддерживается для Claude Sonnet 4.5 и позже и Claude Opus 4.5 и позже.
Управляйте поведением tool search с помощью переменной окружения ENABLE_TOOL_SEARCH:
| Значение | Поведение |
|---|---|
| (не установлено) | Все инструменты MCP откладываются и загружаются по требованию. Возвращается к загрузке заранее на Vertex AI или когда ANTHROPIC_BASE_URL является хостом, не являющимся первой стороной |
true |
Все инструменты MCP откладываются. Claude Code отправляет заголовок бета-версии даже на Vertex AI и через прокси. Запросы завершаются ошибкой на моделях Vertex AI ранее, чем 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
Для организаций, которым требуется централизованный контроль над тем, какие MCP servers пользователи могут подключать, см. Managed MCP configuration. Это охватывает развертывание фиксированного набора servers с помощью managed-mcp.json, ограничение servers с помощью allowedMcpServers и deniedMcpServers, а также то, что видят пользователи, когда server заблокирован.