--- title: Справочник по туннелям MCP url: https://platform.claude.com/docs/ru/agents-and-tools/mcp-tunnels/reference description: Поля конфигурации прокси, REST API туннелей, требования к сертификатам и компонент настройки. --- «MCP tunnels» (туннели MCP) находятся на этапе «research preview» (исследовательская предварительная версия). [Запросите доступ](https://claude.com/form/mcp-tunnels), чтобы опробовать их. ## Конфигурация прокси [Прокси](https://platform.claude.com/docs/ru/agents-and-tools/mcp-tunnels/concepts#components) читает свою конфигурацию из `/etc/mcp-gateway/config.yaml` (Compose) или из сформированного ConfigMap (Helm, заполняется из `gateway.config.*`). | Поле | Описание | По умолчанию | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | `listen_addr` | Адрес и порт для прослушивания. | Обязательно | | `log_level` | Уровень детализации журналирования: `debug`, `info`, `warn` или `error`. | `info` | | `shutdown_timeout` | Как долго ждать завершения выполняющихся запросов при корректном завершении работы. | `30s` | | `tunnel_domain` | Базовый домен, назначенный туннелю. Если задан, при поиске маршрута этот суффикс удаляется из входящих имён хостов, так что ключи `routes` могут быть простыми поддоменами (`wiki`). Если пуст, ключи `routes` должны быть точными полными именами хостов. | Обязательно, если ключи `routes` являются простыми поддоменами | | `tls.cert_file` | Путь к серверному TLS-сертификату. | Обязательно | | `tls.key_file` | Путь к закрытому ключу серверного TLS. | Обязательно | | `routes` | Отображение поддомена или полного имени хоста на URL вышестоящего сервера. См. [Сопоставление маршрутов](https://platform.claude.com/docs/ru/agents-and-tools/mcp-tunnels/reference#route-matching). | Обязательно | | `upstream.allowed_ips` | Диапазоны IPv4 CIDR или отдельные адреса, к которым прокси разрешено подключаться. Взаимоисключающее с `disable_ip_validation`. | Частные диапазоны RFC1918 | | `upstream.disable_ip_validation` | Полностью отключить проверку IP вышестоящего сервера. Взаимоисключающее с `allowed_ips`. | `false` | | `upstream.tls.ca_file` | Набор сертификатов CA для проверки TLS вышестоящего сервера. | Нет | | `upstream.tls.include_system_cas` | Также доверять системному набору сертификатов CA для TLS вышестоящего сервера. | `false` | Для вышестоящих маршрутов `https://` задайте хотя бы один из параметров `upstream.tls.ca_file` или `upstream.tls.include_system_cas`; в противном случае у прокси не будет якоря доверия для сертификата вышестоящего сервера. ### Сопоставление маршрутов `routes` — это плоское отображение строк (`map[string]string`), а не список. Прокси сначала ищет входящее имя хоста по точному совпадению, затем удаляет суффикс `tunnel_domain` и сопоставляет оставшийся поддомен. При сопоставлении учитывается только имя хоста; путь запроса и строка запроса передаются [вышестоящему серверу MCP](https://platform.claude.com/docs/ru/agents-and-tools/mcp-tunnels/concepts#components) без изменений. Каждое значение вышестоящего сервера должно иметь строго вид `scheme://host:port`. Порт обязателен. Указание пути отклоняется при загрузке конфигурации с ошибкой `invalid upstream (must be scheme://host:port)`. ## API туннелей REST API туннелей находится по адресу `/v1/tunnels` и поддерживает создание, получение списка и архивирование туннелей, регистрацию сертификатов CA, а также раскрытие или ротацию токена туннеля. См. [справочник по API туннелей](https://platform.claude.com/docs/ru/api/beta/tunnels/list), где описаны все конечные точки, схемы запросов и ответов, а также примеры. Прежняя поверхность Admin API по адресу `/v1/organizations/tunnels` (бета-заголовок `mcp-tunnels-2026-05-19`, область действия `org:manage_tunnels`) продолжает работать в течение периода миграции и остаётся задокументированной в [справочнике по Admin API](https://platform.claude.com/docs/ru/api/beta/organization/mcp_tunnels) с уведомлением об устаревании. Для миграции обновите путь на `/v1/tunnels`, бета-заголовок на `mcp-tunnels-2026-06-22`, а область действия вашего токена WIF на `workspace:manage_tunnels`. Все конечные точки туннелей MCP требуют bearer-токен с областью действия `workspace:manage_tunnels`, полученный через [Workload Identity Federation](https://platform.claude.com/docs/ru/manage-claude/workload-identity-federation) (федерацию удостоверений рабочих нагрузок), или WIF. Ключи Admin API не принимаются. Обязательные заголовки в каждом запросе: | Заголовок | Значение | | ------------------- | ------------------------------------------------------------ | | `Authorization` | `Bearer ` (токен, полученный в результате обмена WIF) | | `anthropic-version` | `2023-06-01` | | `anthropic-beta` | `mcp-tunnels-2026-06-22` | ## Требования к сертификатам [Компонент настройки](https://platform.claude.com/docs/ru/agents-and-tools/mcp-tunnels/concepts#components) автоматически генерирует соответствующие требованиям сертификаты. Эти требования применяются только в том случае, если вы выпускаете сертификаты через собственную PKI. ### Сертификат CA Загружается с помощью `POST /v1/tunnels/{tunnel_id}/certificates`. Туннель может одновременно содержать до двух активных сертификатов CA, что позволяет выполнять ротацию без простоя. * В кодировке PEM, один сертификат, размером до 8 кБ. * Присутствует расширение `BasicConstraints` со значением `CA:TRUE`, помеченное как критическое. * Присутствует расширение `SubjectKeyIdentifier`. * `KeyUsage` включает `keyCertSign`. * В пределах срока действия. * RSA 2048 бит или больше либо ECDSA P-256 или больше, с подписью SHA-256 или более стойкой. ### Серверный сертификат Предъявляется прокси во время [внутреннего TLS](https://platform.claude.com/docs/ru/agents-and-tools/mcp-tunnels/concepts#components). * Подписан непосредственно зарегистрированным CA (без промежуточных сертификатов). * Присутствует расширение `AuthorityKeyIdentifier`, совпадающее с `SubjectKeyIdentifier` CA. * Subject Alternative Name включает DNS-имя, соответствующее `.`. Подстановочный знак `*.` покрывает все маршруты. * Если присутствует расширение `ExtendedKeyUsage`, оно включает `serverAuth`. * В пределах срока действия. * RSA 2048 бит или больше либо ECDSA P-256 или больше, с подписью SHA-256 или более стойкой. Компонент настройки генерирует CA ECDSA P-256 со сроком действия пять лет и серверный сертификат RSA 4096 бит с подстановочным SAN и сроком действия 90 дней. ## Компонент настройки Компонент настройки поставляется внутри образа `mcp-proxy` в виде исполняемого файла `setup`. Запускайте его командой `docker compose run --rm setup ` (Compose) или полагайтесь на хуки и CronJob чарта (Helm). ### `setup init` Подключается к существующему туннелю (или создаёт новый, если идентификатор туннеля не указан), затем генерирует CA и серверный сертификат, регистрирует CA, получает токен туннеля и записывает все результаты в место назначения. | Флаг | Описание | По умолчанию | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | | `--api-url` | Базовый URL Claude API. Также читается из `API_URL`. | Обязательно | | `--tunnel-id` | Идентификатор туннеля для подключения (`tnl_...`). Также читается из `TUNNEL_ID`. Если не указан, создаётся новый туннель; идентификатор туннеля, уже сохранённый в выходных данных, повторно используется при последующих запусках. | Нет (создать туннель) | | `--output` | Место назначения вывода: `dir:/path` или `k8s-secret:NAME`. Чарт Helm передаёт `k8s-secret:`. | `k8s-secret:mcp-tunnel` (определяется автоматически при запуске в поде Kubernetes; в остальных случаях обязательно) | | `--cert-duration` | Срок действия серверного сертификата. | `2160h` (90 дней) | | `--token-version` | Строка для обнаружения изменений. Новое значение запускает ротацию токена при повторном запуске. И чарт Helm, и пример Compose передают `1` в качестве начального значения. | Нет | Команда выполняет аутентификацию через [Workload Identity Federation](https://platform.claude.com/docs/ru/manage-claude/workload-identity-federation). Она читает `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_WORKSPACE_ID` (необязательно) и ровно одну из переменных `ANTHROPIC_IDENTITY_TOKEN_FILE` или `ANTHROPIC_IDENTITY_TOKEN`. Актуальную семантику этих переменных см. в [справочнике по WIF](https://platform.claude.com/docs/ru/manage-claude/wif-reference); компонент настройки определяет сервисный аккаунт по правилу федерации, поэтому ему не требуется отдельно `ANTHROPIC_SERVICE_ACCOUNT_ID`. ### `setup renew-cert` Выпускает новый серверный сертификат, подписанный сохранённым CA. Не выполняет вызовов API. | Флаг | Описание | По умолчанию | | ----------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- | | `--output` | Место назначения вывода: `dir:/path` или `k8s-secret:NAME`. Чарт Helm передаёт `k8s-secret:`. | `k8s-secret:mcp-tunnel` (определяется автоматически при запуске в поде Kubernetes; в остальных случаях обязательно) | | `--cert-duration` | Срок действия нового сертификата. | `2160h` (90 дней) | | `--renew-before` | Пропустить обновление, если у существующего сертификата осталось больше указанного срока. | `0` (всегда обновлять) | Установка `--renew-before=720h` превращает команду в пустую операцию, если остаётся более 30 дней срока действия, поэтому её безопасно запускать по фиксированному расписанию.