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

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

Краткая справка

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

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

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

1. 1

   Добавьте маршрут прокси для сервера авторизации

   routes:
     mcp: http://your-mcp-server:8080
     auth: http://your-auth-server:8080

   

   Перезапустите прокси после редактирования routes (docker compose restart mcp-proxy или helm upgrade).

2. 2

   Отдавайте метаданные обнаружения с разделёнными конечными точками

   Ответ /.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"]
   }

   
3. 3

   Направьте сервер MCP на издателя в туннеле

   Ответ /.well-known/oauth-protected-resource вашего сервера MCP должен ссылаться на имя хоста туннеля как на свой сервер авторизации:

   {
     "resource": "https://mcp.<tunnel-domain>",
     "authorization_servers": ["https://auth.<tunnel-domain>"]
   }

   

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

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

Компонент настройки (setup component) — Helm Job или сервис Compose setup — аутентифицируется в 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 после успешного обмена означает, что область действия (scope) правила не включает workspace: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:

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