Подключение MCP-серверов в Claude Code

В предыдущей статье мы разобрали архитектуру MCP: три роли (Host/Client/Server), три примитива (tools/resources/prompts) и два транспорта (stdio и streamable HTTP). Теперь переходим к практике — как именно подключить сервер к конкретному проекту, где хранится конфигурация и как не наделать ошибок с безопасностью.

Центральная команда: `claude mcp add`

Всё управление MCP-серверами идёт через подкоманду claude mcp. Базовый синтаксис зависит от типа транспорта.

Для HTTP-серверов (облачные сервисы):

# Подключить удалённый сервер по HTTP
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# С заголовком авторизации (статический токен)
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

Для stdio-серверов (локальные процессы):

# Важно: двойное тире -- отделяет флаги claude от команды сервера
claude mcp add --transport stdio airtable --env AIRTABLE_API_KEY=key123 \
  -- npx -y airtable-mcp-server

# PostgreSQL через локальный прокси
claude mcp add --transport stdio db \
  -- npx -y @bytebase/dbhub --dsn "postgresql://ro:pass@localhost:5432/prod"

Обратите внимание на -- (двойное тире): без него Claude Code попытается разобрать аргументы сервера как собственные флаги и выдаст ошибку. Это классическая ловушка при первом знакомстве с stdio-серверами.

Check yourself

Вы хотите подключить stdio-сервер командой: `claude mcp add --transport stdio myserver -- python server.py --port 8080`. Что произойдёт, если убрать `--` и написать `claude mcp add --transport stdio myserver python server.py --port 8080`?

Управление подключёнными серверами — несколько команд, которые нужно знать:

claude mcp list          # Показать все серверы и их статус
claude mcp get github    # Детали конкретного сервера
claude mcp remove github # Удалить сервер

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

/mcp

MCP Servers
──────────────────────────────────────────
● github        Connected        42 tools
● sentry        Connected         8 tools
! notion        Auth Required       [Connect]
○ local-db      Disconnected

Три скоупа: где хранится конфигурация

Скоуп определяет два параметра: где физически лежит конфигурация и кто ещё её видит.

graph TD A[claude mcp add] --> B{--scope?} B -->|local (по умолчанию)| C[~/.claude.json под путём проекта] B -->|project| D[.mcp.json в корне проекта] B -->|user| E[~/.claude.json глобально] C --> F[Только вы, текущий проект] D --> G[Вся команда через git] E --> H[Только вы, все проекты]

graph TD
    A[claude mcp add] --> B{--scope?}
    B -->|local (по умолчанию)| C[~/.claude.json<br/>под путём проекта]
    B -->|project| D[.mcp.json<br/>в корне проекта]
    B -->|user| E[~/.claude.json<br/>глобально]
    C --> F[Только вы,<br/>текущий проект]
    D --> G[Вся команда<br/>через git]
    E --> H[Только вы,<br/>все проекты]

Три скоупа MCP-серверов: куда пишется конфигурация и кто её видит

Local (по умолчанию) — сервер доступен только вам, только в текущем проекте. Хранится в ~/.claude.json под путём проекта. Никуда не идёт в git, никто другой не видит.

# Оба вызова эквивалентны — local является дефолтом
claude mcp add --transport http stripe https://mcp.stripe.com
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

Project — сервер доступен всей команде, потому что конфигурация пишется в .mcp.json в корне проекта. Этот файл коммитится в git. Каждый член команды, открыв проект, увидит тот же сервер.

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

Результат — появляется или обновляется .mcp.json:

{
  "mcpServers": {
    "paypal": {
      "type": "http",
      "url": "https://mcp.paypal.com/mcp"
    }
  }
}

User — сервер доступен вам во всех проектах. Тоже хранится в ~/.claude.json, но не привязан к конкретному проекту.

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

Таблица для быстрой сверки:

Скоуп	Загружается в	Видят другие	Хранится
`local`	Текущий проект	Нет	`~/.claude.json`
`project`	Текущий проект	Да, через git	`.mcp.json`
`user`	Все проекты	Нет	`~/.claude.json`

Check yourself

Менеджер попросил настроить MCP-сервер для внутренней базы данных так, чтобы все разработчики команды автоматически получили его при клонировании репозитория. Какой скоуп нужно использовать и что попадёт в git?

Файл `.mcp.json`: ручная конфигурация и переменные окружения

Файл .mcp.json — это не просто артефакт claude mcp add, его можно и нужно редактировать руками, особенно для командных настроек. Типичная ситуация: конфиг коммитится в репозиторий, но каждый разработчик подставляет свой API-ключ через переменную окружения.

Claude Code поддерживает расширение переменных прямо в .mcp.json:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    },
    "local-db": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"],
      "env": {
        "LOG_LEVEL": "${LOG_LEVEL:-info}"
      }
    }
  }
}

Синтаксис ${VAR:-default} — стандартный shell-стиль: если переменная не задана, используется значение после :-. Расширение работает в полях command, args, env, url и headers. Если переменная обязательна и не задана (без дефолта) — Claude Code не сможет разобрать конфиг.

На практике это означает: в .mcp.json можно смело коммитить URLs и имена серверов, но секреты (токены, пароли) выносить в .env или системное окружение. В .gitignore добавляется .env, но не .mcp.json.

Транспорты в деталях

Мы уже разбирали stdio и streamable HTTP в предыдущей статье на уровне протокола. Здесь — практические нюансы подключения.

Streamable HTTP — рекомендованный вариант для облачных сервисов. В JSON-конфиге тип называется streamable-http (по спецификации), но CLI принимает оба варианта — и http, и streamable-http.

{
  "mcpServers": {
    "my-api": { "type": "streamable-http", "url": "https://api.example.com/mcp" }
  }
}

SSE (Server-Sent Events) — устаревший транспорт, официально deprecated. Если сервер предлагает выбор, берите HTTP. Некоторые старые серверы ещё используют SSE, поэтому поддержка есть, но новые интеграции на нём строить не стоит.

WebSocket — для серверов, которые пушат события сами (CI-уведомления, мониторинг). Не поддерживает OAuth и флаг --transport в CLI, конфигурируется только через .mcp.json или claude mcp add-json:

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

OAuth для удалённых серверов

Большинство облачных MCP-серверов (Sentry, Notion, Slack и другие) требуют аутентификации через OAuth 2.0. Процесс — двухшаговый:

1. Добавляете сервер командой claude mcp add — без токена, просто URL.

2. Запускаете /mcp внутри Claude Code и следуете инструкциям в браузере.

# Шаг 1: добавить
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# Шаг 2: внутри сессии запустить /mcp → кнопка Connect → браузер открывается автоматически

Claude Code обнаруживает, что сервер вернул 401 Unauthorized, и помечает его в /mcp как требующий аутентификации. Токены хранятся в системном keychain (macOS) или в файле credentials — не в .mcp.json. Автоматически обновляются при истечении.

Если OAuth-провайдер требует заранее зарегистрированного redirect_uri (не поддерживает Dynamic Client Registration), нужно явно задать порт и предварительно зарегистрировать приложение:

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

Флаг --client-secret без значения включает masked-ввод в терминале — секрет не попадёт в историю shell. Для CI вместо этого используется переменная окружения MCP_CLIENT_SECRET.

Check yourself

Вы добавили сервер Sentry командой `claude mcp add --transport http sentry https://mcp.sentry.dev/mcp`. При первом использовании Claude Code не может получить данные — возникает ошибка 401. Каков следующий шаг?

Безопасность: что важно знать до подключения

MCP-серверы выполняют инструменты от вашего имени. Несколько правил, которые стоит соблюдать всегда:

Проверяйте источник сервера. Сервер, загружающий внешний контент (веб-страницы, документы, ответы API), потенциально может передать Claude враждебные инструкции — это prompt injection. Для незнакомых серверов читайте исходники или ищите аудиты безопасности.

Давайте минимальные права. Для GitHub PAT выбирайте только нужные репозитории с минимальным набором разрешений — не repo:write для всего аккаунта, когда достаточно read-only на один репозиторий. Для БД используйте read-only пользователя, если вам не нужны записи.

Проект-скоуп требует явного одобрения. Claude Code не подключит .mcp.json-сервер молча — при первом запуске покажет запрос на одобрение. Это защита от случайно подтянутых вредоносных серверов из клонированных репозиториев. Если нужно сбросить выборы одобрения: claude mcp reset-project-choices.

Секреты — в окружение, не в конфиг. .mcp.json коммитится в git. Если туда попал токен — считайте, что он скомпрометирован. Используйте ${VAR} и .env (в .gitignore).

# Плохо — токен в конфиге, который пойдёт в git
{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ghp_реальный_токен_здесь" }
    }
  }
}

# Хорошо — токен из переменной окружения
{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${GITHUB_PAT}" }
    }
  }
}

Диагностика проблем

Несколько распространённых ситуаций и способы их разобрать:

Сервер завис при старте. MCP_TIMEOUT=10000 claude — уменьшить таймаут до 10 секунд, чтобы быстро получать ошибку вместо бесконечного ожидания.
Сервер возвращает слишком много токенов. MAX_MCP_OUTPUT_TOKENS=50000 claude — увеличить лимит (дефолт 25 000 токенов; предупреждение появляется при превышении 10 000 токенов).
HTTP/SSE сервер отпал в середине сессии. Claude Code переподключается автоматически с экспоненциальным backoff (до 5 попыток, начиная с 1 с). Статус виден в /mcp.
Сервер в .mcp.json висит как «Pending approval». Запустите claude интерактивно — появится запрос одобрения.