Implantar túneis MCP com Helm

O Helm chart da Anthropic instala a stack de túnel como um único Deployment e a conecta ao túnel que você criou no Console.

Antes de começar

Você precisa de:

• Um túnel criado no Console. Conclua primeiro Criar um túnel e anote o ID do túnel (tnl_...). Para provisionamento manual, você também precisa do token do túnel e do domínio do túnel obtidos nessa etapa.
• Uma forma de o chart se autenticar na Tunnels API.
  • Acesso programático (recomendado). O componente de setup se autentica por meio de Workload Identity Federation, obtém o token do túnel, gera uma CA, registra-a na Anthropic e armazena tudo em um Secret. Você precisará de uma regra de federação com escopo org:manage_tunnels.
  • Manual. Ignore o acesso programático. Você vai obter o token do túnel no Console, gerar uma CA e um certificado de servidor por conta própria, registrar a CA no Console e fornecer as credenciais ao cluster como Secrets.
• Um cluster Kubernetes no qual você possa fazer deploy com helm e kubectl. A aba Sem acesso programático também usa openssl (1.1.1 ou posterior).
• Conectividade de rede de saída do cluster para api.anthropic.com (443 TCP) e para o tunnel edge (7844 TCP e UDP). Consulte os requisitos de rede completos.
• Um ou mais servidores MCP em execução e acessíveis a partir do cluster nos endereços que você configurará em gateway.config.routes. Se você ainda não tiver um, use o servidor de exemplo.

Opcional: Usar um servidor MCP de exemplo

Se você não tiver um servidor MCP disponível para testes, use este servidor mínimo:

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

As etapas de instalação a seguir indicam onde adicionar a rota correspondente.

Instalar

Verificar a implantação

Verifique de ponta a ponta a partir do lado da Anthropic: use https://<route>.<your-tunnel-domain>/<path> em uma sessão de Managed Agent ou em uma requisição à Messages API, onde <route> é uma chave de gateway.config.routes e <path> é o que quer que o servidor MCP upstream sirva nesse caminho. Com o servidor MCP de exemplo, isso é https://echo.<your-tunnel-domain>/mcp. Consulte Usar os servidores MCP tunelados para os formatos de requisição.

Se isso falhar, verifique os logs do pod (kubectl -n mcp-tunnel logs deploy/mcp-tunnel -c mcp-proxy e -c cloudflared) e consulte Solução de problemas.

Configuração opcional

Restringir egress com NetworkPolicy

O ingress para o pod do proxy é negado por padrão (networkPolicy.ingress.enabled: true). Para restringir adicionalmente o egress do pod, defina networkPolicy.egress.enabled: true e preencha networkPolicy.egress.mcpServers com seletores de label de pod ou intervalos CIDR que cubram seus servidores MCP upstream. O egress do cloudflared para o tunnel edge é permitido separadamente por meio de networkPolicy.egress.cloudflaredEgressCIDRs.

Ajustar o proxy

Os campos em gateway.config.* são repassados para o arquivo de configuração do proxy. Ajustes comuns incluem upstream.allowed_ips, log_level e upstream.tls. Consulte a referência de configuração do proxy para a lista completa de campos. O chart sempre define listen_addr, tls.cert_file e tls.key_file; defini-los em gateway.config não tem efeito.

Fornecer seu próprio token OIDC

Por padrão, o chart projeta um token de ServiceAccount do Kubernetes para o componente de setup. Para usar um token de um provedor de identidade diferente (como SPIFFE, Vault ou um sidecar de SDK de nuvem), monte-o com setup.extraVolumes e setup.extraVolumeMounts. Em seguida, aponte api.wif.tokenFile para o caminho de montagem. O chart define ANTHROPIC_IDENTITY_TOKEN_FILE para esse caminho, e o componente de setup lê o token a partir dele.

Upgrades

Sempre passe --version para helm upgrade para não puxar um chart mais recente inesperadamente.

Alterar configuração

Para alterações rotineiras, como rotas, contagem de réplicas ou 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

Rotacionar o token do túnel

Com acesso programático, incremente tunnel.tokenVersion em values.yaml e faça upgrade com --set setup.force=true. O componente de setup só é reexecutado em upgrades quando forçado:

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

O componente de setup se autentica com Workload Identity Federation; não há token de API para revogar.

Sem acesso programático, clique em Rotate token na página de detalhes do túnel no Console e, em seguida, atualize o 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

Renovação de certificado

O chart fornece automação, mas você continua responsável por monitorar a expiração e confirmar que a renovação foi concluída.

Com acesso programático, a renovação de certificado é automática. O chart implanta um CronJob (nomeado a partir do fullname do Helm, com sufixo -cert-renew) que executa setup renew-cert diariamente (em serverCert.cronSchedule, padrão 0 0 * * * UTC). O job é um no-op a menos que o certificado esteja dentro de serverCert.renewBefore da expiração (padrão 30 dias). A renovação é local: o job assina um novo certificado com a CA já armazenada no Secret, não faz chamadas de API e precisa apenas do RBAC do Kubernetes que o chart concede. O proxy faz hot-reload do certificado a partir do mount do Secret, então nenhuma reinicialização do Deployment é necessária.

Sem acesso programático, não há CronJob. De dentro do diretório mcp-tunnel/ que você manteve após a instalação, assine um novo certificado de servidor com a CA existente (não regenere a 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 -

O proxy faz hot-reload do certificado a partir do mount do Secret.

Próximos passos