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

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



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

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

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



Обновления

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



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

Чарт 2.0.0 перемещает идентификатор туннеля из api.wif.tunnelId в tunnel.id. Перед обновлением отредактируйте ваш values.yaml: переместите значение tnl_... в tunnel.id и удалите api.wif.tunnelId. Оставить tunnel.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.2 \
  -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.2 \
  -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.



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