Руководства

Настройка MCP в Claude Code: как добавить сервер MCP, поделиться им и устранить неполадки

Опубликовано 30 октября 2026 г. · Проверено 30 октября 2026 г.

MCP (Model Context Protocol) — открытый стандарт подключения AI-инструментов. Сервер MCP даёт Claude Code прямой доступ к вашим инструментам, базам данных и API, так что данные больше не нужно копировать в чат. Эта страница — пошаговая инструкция: какая команда нужна каждому из трёх транспортов, где хранится конфигурация, как поделиться ею с командой, как аутентифицироваться и что проверить при сбое. Она следует документации Anthropic Connect Claude Code to tools via MCP, сверенной с ней 30 октября 2026 г.

Что такое MCP и когда подключать сервер

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

Безопасность: убедитесь, что вы доверяете каждому серверу, прежде чем подключать его. Серверы, получающие внешнее содержимое, могут подвергнуть вас риску prompt injection.

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

Все способы используют claude mcp add. Исходите из того, что вам даёт сервер: адрес https:// означает удалённый сервер, а команда запуска вроде npx — сервер, работающий на вашей машине.

Удалённый сервер HTTP

# Basic syntax
claude mcp add --transport http <name> <url>

# Real example: Connect to Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Example with Bearer token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

В конфигурации JSON поле type принимает streamable-http как алиас http. Запись JSON с url, но без type — ошибка конфигурации: Claude Code читает запись без type как сервер stdio и пропускает её.

Удалённый сервер SSE

Транспорт SSE (Server-Sent Events) устарел; используйте HTTP, где возможно. Некоторые сервисы по-прежнему предоставляют только эндпоинт SSE. Добавляйте их той же командой claude mcp add --transport http <name> <url>: Claude Code сначала пробует HTTP и переключается на SSE, если сервер его не принимает. Для этого автоматического переключения нужен Claude Code v2.1.265 или новее. В более ранней версии или чтобы подключиться по SSE напрямую, передайте --transport sse:

# Basic syntax
claude mcp add --transport sse <name> <url>

# Real example: Connect to Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Example with authentication header
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

Локальный сервер stdio

Серверы stdio работают как локальные процессы на вашей машине.

# Basic syntax
claude mcp add [options] <name> -- <command> [args...]

# Real example: Add Airtable server
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

• -- (двойной дефис) отделяет собственные опции Claude, такие как --transport, --env и --scope, от команды и аргументов, запускающих сервер. Всё после -- передаётся серверу без изменений. Без него Claude Code попытался бы разобрать флаги сервера, например --port, как собственные опции.
• claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080 запускает python server.py --port 8080 с KEY=value в окружении.
• --env принимает несколько пар KEY=value. Если имя сервера идёт сразу за --env, CLI читает имя как ещё одну пару и отклоняет его, поэтому поставьте между --env и именем сервера хотя бы одну другую опцию, например --transport stdio.

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

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

• URL вида https://mcp.example.com/mcp: сервер удалённый. Используйте claude mcp add --transport http example https://mcp.example.com/mcp.
• Команда запуска вида npx -y @example/mcp-server: сервер работает на вашей машине. Поместите всю команду после --: claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server.
• Блок JSON mcpServers: передайте claude mcp add-json объект внутри mcpServers, а не обёртку:

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

С add-json записи url без type сначала нужно добавить "type": "http", "type": "sse" или "type": "ws". Серверы WebSocket настраиваются в .mcp.json или через claude mcp add-json, потому что claude mcp add --transport не принимает ws. Имя сервера может содержать только буквы, цифры, дефисы и подчёркивания.

Области: где хранится конфигурация

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

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

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

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

Сервер в области local хранится в ~/.claude.json под путём этого проекта, поэтому в других проектах не появляется. Используйте её для личных серверов разработки, экспериментальных конфигураций и серверов с учётными данными, которые не должны попасть в систему контроля версий. Заметьте, что «local scope» для серверов MCP — это не то же самое, что общий локальный файл настроек .claude/settings.local.json.

Когда один и тот же сервер определён в нескольких местах, Claude Code подключается к нему один раз, используя определение из источника с наивысшим приоритетом. Запись используется целиком; поля из разных областей не объединяются. Порядок, от высшего: область local, область project, область user, серверы из плагинов, коннекторы claude.ai.

Общий доступ к серверу для команды через .mcp.json

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

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

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

Переменные окружения в .mcp.json

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

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

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

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

Просмотр, проверка и удаление серверов

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get notion

# Remove a server
claude mcp remove notion

# (within Claude Code) Check server status
/mcp

При успехе claude mcp add выводит строку Added ..., которая означает, что конфигурация записана. Он не проверяет учётные данные, поэтому токен-заглушка принимается, а сервер потом не подключается. Чтобы убедиться, что Claude Code действительно подключился, выполните claude mcp get <name> или /mcp в Claude Code и найдите галочку в строке сервера.

claude mcp list показывает статус состояния рядом с каждым сервером:

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

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

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

Многим облачным серверам MCP требуется аутентификация, и Claude Code поддерживает OAuth 2.0. Он помечает удалённый сервер как требующий аутентификации, когда сервер отвечает 401 Unauthorized или 403 Forbidden.

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

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

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

Чтобы войти, не открывая сессию, выполните процедуру из оболочки:

claude mcp login sentry

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

Если вы настроили для сервера headers.Authorization, а сервер его отклоняет, Claude Code сообщает о неудаче подключения, а не переходит на OAuth. Проверьте, что токен действителен для эндпоинта MCP, или удалите заголовок, чтобы использовать процедуру OAuth. В запуске claude -p или Agent SDK нет панели /mcp, поэтому сначала войдите из интерактивной сессии или командой claude mcp login <name>.

Тайм-ауты и ограничения вывода

• Тайм-аут запуска задаётся переменной окружения MCP_TIMEOUT; например, MCP_TIMEOUT=10000 claude задаёт 10 секунд.
• Чтобы ограничить вызов инструмента для одного сервера, добавьте поле timeout в миллисекундах в запись этого сервера в .mcp.json, например "timeout": 600000 для десяти минут. Оно переопределяет переменную окружения MCP_TOOL_TIMEOUT только для этого сервера.
• Claude Code показывает предупреждение, когда вывод инструмента MCP превышает 10 000 токенов, и по умолчанию ограничивает вывод 25 000 токенами. Чтобы поднять лимит, задайте MAX_MCP_OUTPUT_TOKENS в оболочке перед запуском Claude Code:

export MAX_MCP_OUTPUT_TOKENS=50000
claude

Порог предупреждения фиксирован. Если сервер не повышает собственный лимит инструмента, успешные текстовые результаты длиннее 50 000 символов сохраняются в файл независимо от этой переменной.

Устранение неполадок

FAQ

Источники

• Claude Code: Connect Claude Code to tools via MCP (claude mcp add, области, .mcp.json, аутентификация, ограничения вывода; проверено 30 октября 2026 г.)