Развёртывание MCP-туннелей с помощью Helm

Helm-чарт Anthropic устанавливает стек туннеля как единый Deployment и подключает его к туннелю, который вы создали в Console.

Перед началом работы

Вам потребуется:

• Туннель, созданный в Console. Сначала выполните шаг Создание туннеля и запишите идентификатор туннеля (tnl_...). Для ручной настройки вам также понадобятся токен туннеля и домен туннеля, полученные на этом шаге.
• Способ аутентификации чарта в Tunnels API.
  • Программный доступ (рекомендуется). Компонент setup аутентифицируется через Workload Identity Federation, получает токен туннеля, генерирует CA, регистрирует его в Anthropic и сохраняет всё в Secret. Вам понадобится правило федерации с областью действия org:manage_tunnels.
  • Ручной. Пропустите программный доступ. Вы получите токен туннеля из Console, самостоятельно сгенерируете CA и серверный сертификат, зарегистрируете CA в Console и передадите учётные данные в кластер в виде Secrets.
• Кластер Kubernetes, в который вы можете выполнять развёртывание с помощью helm и kubectl. На вкладке Без программного доступа также используется openssl (версии 1.1.1 или новее).
• Исходящее сетевое подключение из кластера к api.anthropic.com (443 TCP) и к границе туннеля (7844 TCP и UDP). См. полные сетевые требования.
• Один или несколько MCP-серверов, запущенных и доступных из кластера по адресам, которые вы настроите в gateway.config.routes. Если у вас ещё нет такого сервера, используйте пример сервера.

Необязательно: использование примера MCP-сервера

Если у вас нет MCP-сервера для тестирования, используйте этот минимальный вариант:

kubectl create namespace mcp-tunnel --dry-run=client -o yaml | kubectl apply -f -
kubectl -n mcp-tunnel apply -f - <<'EOF'
apiVersion: v1
kind: ConfigMap
metadata:
  name: hello-mcp-src
data:
  hello_server.py: |
    from mcp.server.fastmcp import FastMCP

    mcp = FastMCP("hello-server", host="0.0.0.0", port=9000)


    @mcp.tool()
    def hello(name: str = "world") -> str:
        """Say hello to someone."""
        return f"Hello, {name}!"


    if __name__ == "__main__":
        mcp.run(transport="streamable-http")
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello-mcp
spec:
  replicas: 1
  selector:
    matchLabels: { app: hello-mcp }
  template:
    metadata:
      labels: { app: hello-mcp }
    spec:
      containers:
        - name: hello-mcp
          image: python:3.13-slim
          command: ["sh", "-c", "pip install --quiet mcp && python /app/hello_server.py"]
          volumeMounts:
            - { name: src, mountPath: /app }
          ports:
            - { containerPort: 9000 }
      volumes:
        - name: src
          configMap: { name: hello-mcp-src }
---
apiVersion: v1
kind: Service
metadata:
  name: hello-mcp
spec:
  selector: { app: hello-mcp }
  ports:
    - { port: 9000, targetPort: 9000 }
EOF

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

Установка

Проверка развёртывания

Проверьте сквозное подключение со стороны Anthropic: используйте https://<route>.<your-tunnel-domain>/<path> в сеансе Managed Agent или в запросе к Messages API, где <route> — ключ из gateway.config.routes, а <path> — то, что обслуживает вышестоящий MCP-сервер. Для примера MCP-сервера это https://echo.<your-tunnel-domain>/mcp. Формы запросов см. в разделе Использование туннелированных MCP-серверов.

Если проверка не проходит, изучите логи пода (kubectl -n mcp-tunnel logs deploy/mcp-tunnel -c mcp-proxy и -c cloudflared) и обратитесь к разделу Устранение неполадок.

Дополнительная настройка

Ограничение исходящего трафика с помощью NetworkPolicy

Входящий трафик к поду прокси по умолчанию запрещён (networkPolicy.ingress.enabled: true). Чтобы дополнительно ограничить исходящий трафик пода, установите networkPolicy.egress.enabled: true и заполните networkPolicy.egress.mcpServers селекторами меток подов или диапазонами CIDR, охватывающими ваши вышестоящие MCP-серверы. Исходящий трафик от cloudflared к границе туннеля разрешается отдельно через networkPolicy.egress.cloudflaredEgressCIDRs.

Тонкая настройка прокси

Поля в gateway.config.* передаются напрямую в файл конфигурации прокси. Типичные настройки включают upstream.allowed_ips, log_level и upstream.tls. Полный список полей см. в справочнике по конфигурации прокси. Чарт всегда задаёт listen_addr, tls.cert_file и tls.key_file; установка их в gateway.config не имеет эффекта.

Предоставление собственного OIDC-токена

По умолчанию чарт проецирует токен Kubernetes ServiceAccount для компонента setup. Чтобы использовать токен от другого поставщика идентификации (например, SPIFFE, Vault или sidecar облачного SDK), смонтируйте его с помощью setup.extraVolumes и setup.extraVolumeMounts. Затем укажите в api.wif.tokenFile путь монтирования. Чарт устанавливает ANTHROPIC_IDENTITY_TOKEN_FILE в этот путь, и компонент setup читает токен оттуда.

Обновления

Всегда передавайте --version в helm upgrade, чтобы случайно не получить более новую версию чарта.

Изменение конфигурации

Для рутинных изменений, таких как маршруты, количество реплик или NetworkPolicy:

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 1.0.0 \
  -n mcp-tunnel \
  -f values.yaml

Ротация токена туннеля

При программном доступе увеличьте tunnel.tokenVersion в values.yaml и выполните обновление с --set setup.force=true. Компонент setup повторно запускается при обновлениях только принудительно:

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 1.0.0 \
  -n mcp-tunnel \
  -f values.yaml \
  --set setup.force=true

Компонент setup аутентифицируется через Workload Identity Federation; токена API, который нужно отзывать, нет.

Без программного доступа нажмите Rotate token на странице сведений о туннеле в Console, затем обновите Secret mcp-tunnel-token:

kubectl -n mcp-tunnel create secret generic mcp-tunnel-token \
  --from-literal=tunnel-token='eyJ...' --dry-run=client -o yaml | kubectl apply -f -
kubectl -n mcp-tunnel rollout restart deploy/mcp-tunnel

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

Чарт обеспечивает автоматизацию, но вы по-прежнему отвечаете за мониторинг срока действия и подтверждение успешного обновления.

При программном доступе обновление сертификата выполняется автоматически. Чарт развёртывает CronJob (названный по Helm fullname с суффиксом -cert-renew), который ежедневно запускает setup renew-cert (по расписанию serverCert.cronSchedule, по умолчанию 0 0 * * * UTC). Задание ничего не делает, если до истечения срока действия сертификата остаётся больше, чем serverCert.renewBefore (по умолчанию 30 дней). Обновление выполняется локально: задание подписывает новый сертификат с помощью CA, уже хранящегося в Secret, не выполняет вызовов API и нуждается только в Kubernetes RBAC, который предоставляет чарт. Прокси выполняет горячую перезагрузку сертификата из смонтированного Secret, поэтому перезапуск Deployment не требуется.

Без программного доступа CronJob отсутствует. Из каталога mcp-tunnel/, который вы сохранили после установки, подпишите новый серверный сертификат существующим CA (не генерируйте CA заново):

export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE
openssl req -new -key data/tls.key -out /tmp/server.csr \
  -subj "/CN=${TUNNEL_DOMAIN}"
openssl x509 -req -in /tmp/server.csr \
  -CA data/ca.crt -CAkey data/ca.key -CAcreateserial \
  -out data/tls.crt -days 90 -extfile data/tls.ext

kubectl -n mcp-tunnel create secret generic mcp-tunnel-cert \
  --from-file=tls.crt=data/tls.crt --from-file=tls.key=data/tls.key \
  --dry-run=client -o yaml | kubectl apply -f -

Прокси выполняет горячую перезагрузку сертификата из смонтированного Secret.

Дальнейшие шаги