СообщенияТуннели MCP

Устранение неполадок MCP-туннелей

Диагностика проблем с подключением, TLS, проверкой IP-адресов и маршрутизацией OAuth в стеке туннеля.

Туннели MCP находятся в стадии исследовательской предварительной версии. Запросите доступ, чтобы попробовать их.

Запрос через туннель может завершиться сбоем на одном из трёх уровней; диагностируйте их по порядку: исходящее соединение с границей туннеля, внутренний TLS от Anthropic к вашему прокси, затем маршрутизация и проверка IP-адресов в направлении вышестоящего MCP-сервера.

Краткий справочник

Симптом	Причина	Решение
Туннель не отображается в селекторе агента + MCP Server	Селектор показывает только туннели в рабочем пространстве сеанса, у которых есть хотя бы один активный сертификат.	Зарегистрируйте сертификат CA или откройте сеанс в том рабочем пространстве, в котором был создан туннель.
Вызывающая сторона видит HTTP 500; cloudflared логирует `No ingress rules were defined`	У cloudflared нет локальной цели.	Добавьте `--url http://localhost:8080` и `network_mode: "service:mcp-proxy"` к сервису cloudflared.
Прокси логирует `no route for host`	`tunnel_domain` не совпадает с назначенным доменом, либо `config.yaml` был отредактирован без перезапуска.	Установите `tunnel_domain` в точности равным домену, указанному на странице сведений о туннеле, затем перезапустите прокси (`docker compose restart mcp-proxy`).
Прокси логирует `IP validation failed: <ip> is not a private address`	Вышестоящий MCP-сервер разрешается в адрес за пределами RFC1918.	См. Проверка IP-адресов вышестоящих серверов.
Прокси завершается с ошибкой `cannot unmarshal !!seq into map[string]string`	`routes` задан как YAML-список.	Используйте `routes: { name: http://host:port }`.
Прокси завершается с ошибкой `open /data/tls.key: permission denied`	Ключ имеет права `0600`; контейнер прокси запускается не от root.	`chmod 644 data/tls.key`.
`curl https://<proxy>:8080` завершается с ошибкой `wrong version number`	Ожидаемое поведение; слушатель — это незашифрованный WebSocket. TLS происходит внутри WS-потока.	Вместо этого проверьте через Managed Agent или Messages API.

В следующих разделах рассматриваются сбои, для устранения которых недостаточно однострочного решения.

OAuth не работает за списком разрешённых исходных IP-адресов

Потоки OAuth завершаются сбоем, когда список разрешённых исходных IP-адресов вашего сервера авторизации блокирует доступ бэкенда Anthropic к /token, /register и конечным точкам обнаружения. Если вы предпочитаете не добавлять в список разрешённых диапазоны исходящих адресов Anthropic, вы можете направить вызовы OAuth «бэкенд-к-бэкенду» через туннель, оставив при этом конечную точку /authorize, обращённую к браузеру, на вашем существующем публичном имени хоста.

Добавьте маршрут прокси для сервера авторизации
routes: mcp: http://your-mcp-server:8080 auth: http://your-auth-server:8080
Перезапустите прокси после редактирования routes (docker compose restart mcp-proxy или helm upgrade).
Предоставьте метаданные обнаружения с разделёнными конечными точками
Ответ /.well-known/oauth-authorization-server вашего сервера авторизации должен указывать authorization_endpoint на ваше существующее имя хоста из списка разрешённых, а всё остальное — на туннель:
{ "issuer": "https://auth.<tunnel-domain>", "authorization_endpoint": "https://<your-allowlisted-host>/authorize", "token_endpoint": "https://auth.<tunnel-domain>/token", "registration_endpoint": "https://auth.<tunnel-domain>/register", "code_challenge_methods_supported": ["S256"] }
Укажите MCP-серверу издателя туннеля
Ответ /.well-known/oauth-protected-resource вашего MCP-сервера должен ссылаться на имя хоста туннеля как на свой сервер авторизации:
{ "resource": "https://mcp.<tunnel-domain>", "authorization_servers": ["https://auth.<tunnel-domain>"] }

При такой конфигурации браузер пользователя обращается к /authorize на вашем существующем имени хоста (которое уже разрешено вашим списком), а бэкенд Anthropic достигает /token, /register и документов обнаружения через туннель.

Сбои аутентификации компонента настройки

Компонент настройки (Helm Job или сервис setup в Compose) аутентифицируется в Tunnels API, обменивая OIDC JWT через ваше правило федерации. Если обмен завершается сбоем, см. Устранение неполадок при сбое обмена в справочнике по Workload Identity Federation; режимы сбоя (subject, audience, issuer, JWKS, время жизни) те же самые.

Причины, специфичные для туннелей:

Значение audience по умолчанию в чарте — api.anthropic.com (без схемы). Если audience вашего правила — https://api.anthropic.com, установите api.wif.audience в соответствующее значение.
Ответ 403 от Tunnels API после успешного обмена означает, что область действия правила не включает org:manage_tunnels, либо сервисный аккаунт правила не является членом рабочего пространства туннеля. Задайте область действия и добавьте сервисный аккаунт в рабочее пространство.

В Helm компонент настройки запускается как Job хука pre-install. При сбое Job остаётся для изучения (kubectl logs job/mcp-tunnel-setup -n mcp-tunnel). Helm не управляет ресурсами хуков, поэтому удалите его перед повторной попыткой:

helm uninstall mcp-tunnel -n mcp-tunnel
kubectl -n mcp-tunnel delete job mcp-tunnel-setup

Туннель не подключается

Сначала проверьте логи cloudflared. Распространённые причины:

TUNNEL_TOKEN отсутствует, истёк или скопирован неправильно.
Брандмауэр блокирует исходящий TCP/UDP на порту 7844 к границе туннеля.

cloudflared также может логировать предупреждения о размерах буфера приёма UDP; это подсказка по настройке QUIC, а не ошибка.

Ошибки сертификатов

Когда Anthropic отклоняет сертификат прокси во время внутреннего TLS, прокси логирует tls handshake failed. Убедитесь, что:

Срок действия серверного сертификата не истёк.
Subject Alternative Name сертификата соответствует *.<tunnel-domain>.
Подписывающий CA зарегистрирован в Anthropic для этого туннеля.

Полные правила проверки см. в требованиях к сертификатам.

Проверка IP-адресов вышестоящих серверов

Для защиты от SSRF прокси по умолчанию устанавливает соединения только с адресами в частных диапазонах RFC1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16). Для соединения прокси с вышестоящим сервером поддерживается только IPv4. (Диапазон исходящих адресов от cloudflared к границе в Сетевых требованиях — это другой переход.)

Если прокси логирует IP validation failed: <ip> is not a private address, имя хоста вышестоящего сервера разрешилось в адрес за пределами этого набора. В Kubernetes некоторые управляемые дистрибутивы выделяют Service CIDR за пределами RFC1918; если kubectl get svc kubernetes -n default -o jsonpath='{.spec.clusterIP}' возвращает адрес за пределами частных диапазонов, найдите Service CIDR вашего кластера и добавьте его.

Если адрес легитимен, добавьте наиболее узкий покрывающий CIDR в upstream.allowed_ips. Установка allowed_ips заменяет значение по умолчанию RFC1918, а не расширяет его, поэтому включите частные диапазоны, которые используют другие ваши вышестоящие MCP-серверы:

config/mcp-proxy.yaml

upstream:
  allowed_ips:
    - 10.0.0.0/8
    - 172.16.0.0/12
    - 192.168.0.0/16
    - 127.0.0.0/8       # loopback, for local testing only

Избегайте 0.0.0.0/0 за пределами локального тестирования; это полностью отключает защиту от SSRF.

Was this page helpful?

СообщенияТуннели MCP

Устранение неполадок MCP-туннелей

Диагностика проблем с подключением, TLS, проверкой IP-адресов и маршрутизацией OAuth в стеке туннеля.

Краткий справочник

Симптом	Причина	Решение
Туннель не отображается в селекторе агента + MCP Server	Селектор показывает только туннели в рабочем пространстве сеанса, у которых есть хотя бы один активный сертификат.	Зарегистрируйте сертификат CA или откройте сеанс в том рабочем пространстве, в котором был создан туннель.
Вызывающая сторона видит HTTP 500; cloudflared логирует `No ingress rules were defined`	У cloudflared нет локальной цели.	Добавьте `--url http://localhost:8080` и `network_mode: "service:mcp-proxy"` к сервису cloudflared.
Прокси логирует `no route for host`	`tunnel_domain` не совпадает с назначенным доменом, либо `config.yaml` был отредактирован без перезапуска.	Установите `tunnel_domain` в точности равным домену, указанному на странице сведений о туннеле, затем перезапустите прокси (`docker compose restart mcp-proxy`).
Прокси логирует `IP validation failed: <ip> is not a private address`	Вышестоящий MCP-сервер разрешается в адрес за пределами RFC1918.	См. Проверка IP-адресов вышестоящих серверов.
Прокси завершается с ошибкой `cannot unmarshal !!seq into map[string]string`	`routes` задан как YAML-список.	Используйте `routes: { name: http://host:port }`.
Прокси завершается с ошибкой `open /data/tls.key: permission denied`	Ключ имеет права `0600`; контейнер прокси запускается не от root.	`chmod 644 data/tls.key`.
`curl https://<proxy>:8080` завершается с ошибкой `wrong version number`	Ожидаемое поведение; слушатель — это незашифрованный WebSocket. TLS происходит внутри WS-потока.	Вместо этого проверьте через Managed Agent или Messages API.

В следующих разделах рассматриваются сбои, для устранения которых недостаточно однострочного решения.

OAuth не работает за списком разрешённых исходных IP-адресов

Добавьте маршрут прокси для сервера авторизации
routes: mcp: http://your-mcp-server:8080 auth: http://your-auth-server:8080
Перезапустите прокси после редактирования routes (docker compose restart mcp-proxy или helm upgrade).
Предоставьте метаданные обнаружения с разделёнными конечными точками
Ответ /.well-known/oauth-authorization-server вашего сервера авторизации должен указывать authorization_endpoint на ваше существующее имя хоста из списка разрешённых, а всё остальное — на туннель:
{ "issuer": "https://auth.<tunnel-domain>", "authorization_endpoint": "https://<your-allowlisted-host>/authorize", "token_endpoint": "https://auth.<tunnel-domain>/token", "registration_endpoint": "https://auth.<tunnel-domain>/register", "code_challenge_methods_supported": ["S256"] }
Укажите MCP-серверу издателя туннеля
Ответ /.well-known/oauth-protected-resource вашего MCP-сервера должен ссылаться на имя хоста туннеля как на свой сервер авторизации:
{ "resource": "https://mcp.<tunnel-domain>", "authorization_servers": ["https://auth.<tunnel-domain>"] }

Сбои аутентификации компонента настройки

Причины, специфичные для туннелей:

Значение audience по умолчанию в чарте — api.anthropic.com (без схемы). Если audience вашего правила — https://api.anthropic.com, установите api.wif.audience в соответствующее значение.
Ответ 403 от Tunnels API после успешного обмена означает, что область действия правила не включает org:manage_tunnels, либо сервисный аккаунт правила не является членом рабочего пространства туннеля. Задайте область действия и добавьте сервисный аккаунт в рабочее пространство.

helm uninstall mcp-tunnel -n mcp-tunnel
kubectl -n mcp-tunnel delete job mcp-tunnel-setup

Туннель не подключается

Сначала проверьте логи cloudflared. Распространённые причины:

TUNNEL_TOKEN отсутствует, истёк или скопирован неправильно.
Брандмауэр блокирует исходящий TCP/UDP на порту 7844 к границе туннеля.

Ошибки сертификатов

Когда Anthropic отклоняет сертификат прокси во время внутреннего TLS, прокси логирует tls handshake failed. Убедитесь, что:

Срок действия серверного сертификата не истёк.
Subject Alternative Name сертификата соответствует *.<tunnel-domain>.
Подписывающий CA зарегистрирован в Anthropic для этого туннеля.

Полные правила проверки см. в требованиях к сертификатам.

Проверка IP-адресов вышестоящих серверов

config/mcp-proxy.yaml

upstream:
  allowed_ips:
    - 10.0.0.0/8
    - 172.16.0.0/12
    - 192.168.0.0/16
    - 127.0.0.0/8       # loopback, for local testing only

Избегайте 0.0.0.0/0 за пределами локального тестирования; это полностью отключает защиту от SSRF.

Was this page helpful?