Déployer des tunnels MCP avec Helm

Le chart Helm d'Anthropic installe la pile de tunnel (tunnel stack) sous la forme d'un unique Deployment et l'attache à votre tunnel : soit un tunnel que le hook de configuration du chart crée pour vous, soit un tunnel existant que vous avez créé dans la Console.

Avant de commencer

Vous avez besoin des éléments suivants :

• Un tunnel. Avec l'accès programmatique, le hook de configuration du chart en crée un pour vous lorsque vous ne fournissez pas d'ID de tunnel ; pour vous attacher à un tunnel existant à la place, créez-le dans la Console et notez l'ID du tunnel (tnl_...). Le provisionnement manuel part toujours d'un tunnel créé dans la Console ; vous aurez également besoin de son jeton de tunnel et de son domaine de tunnel.
• Un moyen pour le chart de s'authentifier auprès de l'API Tunnels.
  • Accès programmatique (recommandé). Le composant de configuration (setup component) s'authentifie via Workload Identity Federation, récupère le jeton de tunnel, génère une autorité de certification (CA), l'enregistre auprès d'Anthropic et stocke le tout dans un Secret. Vous aurez besoin d'une règle de fédération limitée à la portée workspace:manage_tunnels.
  • Manuel. Ignorez l'accès programmatique. Vous obtiendrez le jeton de tunnel depuis la Console, générerez vous-même une CA et un certificat serveur, enregistrerez la CA dans la Console et fournirez les identifiants au cluster sous forme de Secrets.
• Un cluster Kubernetes sur lequel vous pouvez déployer avec helm et kubectl. L'onglet Sans accès programmatique utilise également openssl (1.1.1 ou ultérieur).
• Une connectivité réseau sortante depuis le cluster vers api.anthropic.com (443 TCP) et vers la périphérie du tunnel (tunnel edge) (7844 TCP et UDP). Consultez la liste complète des exigences réseau.
• Un ou plusieurs serveurs MCP en cours d'exécution et accessibles depuis le cluster aux adresses que vous configurerez sous gateway.config.routes. Si vous n'en avez pas encore, utilisez le serveur d'exemple.

Facultatif : utiliser un serveur MCP d'exemple

Si vous ne disposez pas d'un serveur MCP pour les tests, utilisez ce serveur minimal :

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

Les étapes d'installation qui suivent indiquent où ajouter la route correspondante.

Installation

Vérifier le déploiement

Vérifiez de bout en bout du côté d'Anthropic : utilisez https://<route>.<your-tunnel-domain>/<path> dans une session Managed Agent ou une requête à l'API Messages, où <route> est une clé de gateway.config.routes et <path> est le chemin sur lequel le serveur MCP en amont répond. Avec le serveur MCP d'exemple, il s'agit de https://echo.<your-tunnel-domain>/mcp. Consultez Utiliser les serveurs MCP tunnelisés pour les formats de requête.

Si cela échoue, vérifiez les journaux des pods (kubectl -n mcp-tunnel logs deploy/mcp-tunnel -c mcp-proxy et -c cloudflared) et consultez la page Dépannage.

Configuration facultative

Restreindre le trafic sortant avec NetworkPolicy

Le trafic entrant vers le pod du proxy est refusé par défaut (networkPolicy.ingress.enabled: true). Pour restreindre en plus le trafic sortant du pod, définissez networkPolicy.egress.enabled: true et renseignez networkPolicy.egress.mcpServers avec des sélecteurs de labels de pods ou des plages CIDR couvrant vos serveurs MCP en amont. Le trafic sortant de cloudflared vers la périphérie du tunnel est autorisé séparément via networkPolicy.egress.cloudflaredEgressCIDRs.

Ajuster le proxy

Les champs sous gateway.config.* sont transmis tels quels au fichier de configuration du proxy. Les ajustements courants incluent upstream.allowed_ips, log_level et upstream.tls. Consultez la référence de configuration du proxy pour la liste complète des champs. Le chart définit toujours listen_addr, tls.cert_file et tls.key_file ; les définir dans gateway.config n'a aucun effet.

Fournir votre propre jeton OIDC

Par défaut, le chart projette un jeton de ServiceAccount Kubernetes pour le composant de configuration. Pour utiliser un jeton provenant d'un autre fournisseur d'identité (tel que SPIFFE, Vault ou un sidecar de SDK cloud), montez-le avec setup.extraVolumes et setup.extraVolumeMounts. Pointez ensuite api.wif.tokenFile vers le chemin de montage. Le chart définit ANTHROPIC_IDENTITY_TOKEN_FILE sur ce chemin, et le composant de configuration y lit le jeton.

Mises à niveau

Passez toujours --version à helm upgrade afin de ne pas récupérer un chart plus récent de manière inattendue.

Mise à niveau depuis le chart 1.x

Le chart 2.0.0 déplace l'ID du tunnel de api.wif.tunnelId vers tunnel.id. Avant la mise à niveau, modifiez votre values.yaml : déplacez la valeur tnl_... vers tunnel.id et supprimez api.wif.tunnelId. Laisser tunnel.id non défini est sans danger (le composant de configuration réutilise l'ID de tunnel déjà stocké dans le Secret mcp-tunnel lors de sa réexécution), mais le déplacement explicite maintient votre values.yaml exact. Mettez également à jour la portée de votre règle de fédération de org:manage_tunnels vers workspace:manage_tunnels dans la Console.

Modifier la configuration

Pour les modifications courantes telles que les routes, le nombre de réplicas ou la 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

Effectuer la rotation du jeton de tunnel

Avec l'accès programmatique, incrémentez tunnel.tokenVersion dans values.yaml et effectuez la mise à niveau avec --set setup.force=true. Le composant de configuration ne se réexécute lors des mises à niveau que lorsqu'il y est forcé :

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

Le composant de configuration s'authentifie avec Workload Identity Federation ; il n'y a aucun jeton API à révoquer.

Sans accès programmatique, cliquez sur Rotate token sur la page de détail du tunnel dans la Console, puis mettez à jour le 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

Renouvellement des certificats

Le chart fournit une automatisation, mais vous restez responsable de la surveillance de l'expiration et de la confirmation que le renouvellement aboutit.

Avec l'accès programmatique, le renouvellement des certificats est automatique. Le chart déploie un CronJob (nommé d'après le fullname Helm, avec le suffixe -cert-renew) qui exécute setup renew-cert quotidiennement (selon serverCert.cronSchedule, par défaut 0 0 * * * UTC). Le job est sans effet sauf si le certificat se trouve à moins de serverCert.renewBefore de son expiration (30 jours par défaut). Le renouvellement est local : le job signe un nouveau certificat avec la CA déjà stockée dans le Secret, n'effectue aucun appel API et n'a besoin que du RBAC Kubernetes accordé par le chart. Le proxy recharge à chaud le certificat depuis le montage du Secret, de sorte qu'aucun redémarrage du Deployment n'est nécessaire.

Sans accès programmatique, il n'y a pas de CronJob. Depuis le répertoire mcp-tunnel/ que vous avez conservé après l'installation, signez un nouveau certificat serveur avec la CA existante (ne régénérez pas la 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 -

Le proxy recharge à chaud le certificat depuis le montage du Secret.

Étapes suivantes