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

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



Прежде чем начать

Вам понадобится:

• Туннель. При программном доступе хук настройки чарта создает его для вас, если вы не указываете ID туннеля; чтобы вместо этого подключиться к существующему туннелю, создайте его в Console и запишите ID туннеля (tnl_...). Ручное выделение ресурсов всегда начинается с туннеля, созданного в Console; вам также понадобятся его токен туннеля и домен туннеля.
• Способ аутентификации чарта в Tunnels API.
  • Программный доступ (рекомендуется). Компонент настройки аутентифицируется через Workload Identity Federation, получает токен туннеля, генерирует CA, регистрирует его в Anthropic и сохраняет все в Secret. Вам понадобится правило федерации с областью действия workspace: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 для компонента настройки. Чтобы использовать токен от другого поставщика удостоверений (например, SPIFFE, Vault или sidecar облачного SDK), смонтируйте его с помощью setup.extraVolumes и setup.extraVolumeMounts. Затем укажите api.wif.tokenFile на путь монтирования. Чарт устанавливает ANTHROPIC_IDENTITY_TOKEN_FILE в этот путь, и компонент настройки читает токен оттуда.



Обновления

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



Обновление с чарта 1.x

Чарт 2.0.0 перемещает ID туннеля из api.wif.tunnelId в tunnel.id. Перед обновлением отредактируйте ваш values.yaml: переместите значение tnl_... в tunnel.id и удалите api.wif.tunnelId. Оставить tunnel.id незаданным безопасно (компонент настройки повторно использует ID туннеля, уже сохраненный в Secret mcp-tunnel при повторном запуске), но явное перемещение сохраняет точность вашего values.yaml. Также обновите область действия вашего правила федерации с org:manage_tunnels на workspace:manage_tunnels в Console.



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

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

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



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

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

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

Компонент настройки аутентифицируется с помощью 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.



Следующие шаги