--- title: Déployer des tunnels MCP avec Helm url: https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/deploy-helm description: Installez la pile de tunnel sur un cluster Kubernetes à l'aide du chart Helm d'Anthropic. --- Les « MCP tunnels » (tunnels MCP) sont en « research preview » (aperçu de recherche). [Demandez l'accès](https://claude.com/form/mcp-tunnels) pour les essayer. Le chart Helm d'Anthropic installe la [pile de tunnel](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/concepts#components) (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](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/console#create-a-tunnel). ## 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](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/console#create-a-tunnel) 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](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/concepts#credential-provisioning) (recommandé).** Le [composant de configuration](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/concepts#components) (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](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/concepts#credential-provisioning).** Ignorez l'accès programmatique. Vous [obtiendrez le jeton de tunnel depuis la Console](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/console#get-the-connection-details), générerez vous-même une CA et un certificat serveur, [enregistrerez la CA dans la Console](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/console#add-a-ca-certificate) 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](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/concepts#components) (tunnel edge) (7844 TCP et UDP). Consultez la liste complète des [exigences réseau](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/overview#network-requirements). * **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](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server). ## Facultatif : utiliser un serveur MCP d'exemple Si vous ne disposez pas d'un serveur MCP pour les tests, utilisez ce serveur minimal : ```bash 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 Le composant de configuration échange le jeton de ServiceAccount projeté du cluster via votre règle de fédération, récupère le jeton de tunnel, génère une CA et un certificat serveur, puis enregistre la CA auprès d'Anthropic. Un CronJob quotidien renouvelle le certificat serveur selon les besoins, de sorte que vous ne manipulez aucun secret à la main. Suivez [Utiliser WIF avec Kubernetes](https://platform.claude.com/docs/fr/manage-claude/wif-providers/kubernetes) pour enregistrer l'émetteur OIDC de votre cluster et créer une règle de fédération. Le composant de configuration s'exécute sous son propre ServiceAccount dans l'espace de noms de la release ; le nom exact suit la convention `fullname` de Helm, donc pour tout nom de release autre que `mcp-tunnel`, exécutez `helm template ... | grep -A2 'kind: ServiceAccount'` pour le confirmer avant de créer la règle. Le reste de ce guide suppose le nom de release `mcp-tunnel` dans l'espace de noms `mcp-tunnel`, où le ServiceAccount est `mcp-tunnel-setup`. | Champ | Valeur | | -------- | -------------------------------------------------------------- | | Sujet | `system:serviceaccount:mcp-tunnel:mcp-tunnel-setup` | | Audience | `api.anthropic.com` (valeur par défaut du chart ; sans schéma) | | Portée | `workspace:manage_tunnels` | L'audience par défaut du chart est `api.anthropic.com` sans schéma, mais le formulaire de règle de fédération de la Console suggère `https://api.anthropic.com`. Les deux doivent correspondre octet pour octet, sinon l'authentification échoue. Définissez l'audience de la règle sur `api.anthropic.com`, ou définissez `api.wif.audience` dans `values.yaml` sur `https://api.anthropic.com`. Si le tunnel se trouve dans un espace de travail autre que celui par défaut de l'organisation, [ajoutez également le compte de service de la règle à cet espace de travail](https://platform.claude.com/docs/fr/manage-claude/workspaces#role-inheritance) (l'API Tunnels effectue l'autorisation en fonction des appartenances du compte de service aux espaces de travail). Notez l'ID de la règle (`fdrl_...`) ; vous le définirez comme `api.wif.federationRuleId`. Le CronJob quotidien de renouvellement de certificat utilise un ServiceAccount distinct (également dérivé du `fullname` Helm) mais n'appelle pas l'API Tunnels ; il renouvelle le certificat localement et n'a besoin que du RBAC Kubernetes, que le chart accorde. La règle de fédération n'a pas besoin de le couvrir. ```bash helm show values \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.0.2 > values.yaml ``` Modifiez `values.yaml` et définissez les clés `api.wif.*` avec l'ID de la règle de fédération et l'ID de l'organisation, ainsi qu'une entrée `routes` pour chaque [serveur MCP en amont](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/concepts#components) (upstream MCP server) : ```yaml values.yaml api: wif: federationRuleId: "fdrl_..." organizationId: "00000000-0000-0000-0000-000000000000" # Set when the tunnel is in a non-default workspace and the # rule's service account is a member of that workspace. # workspaceId: "wrkspc_..." tunnel: # Leave empty to have the setup hook create a tunnel during install. # Set to attach to an existing tunnel from the Console. id: "" # Increment to rotate the tunnel token on the next upgrade. # See the "Rotate the tunnel token" section. tokenVersion: "1" gateway: config: routes: docs: http://docs-mcp.internal:8080 search: http://search-mcp.internal:8080 ``` Avec ces routes, Claude atteint les serveurs à `docs.` et `search.`. Certaines distributions Kubernetes managées allouent le CIDR des Services en dehors des plages privées standard ; si vos routes ciblent des Services internes au cluster, ajoutez ici `gateway.config.upstream.allowed_ips` conformément à la section [Validation des IP en amont](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/troubleshooting#upstream-ip-validation). Si vous utilisez le [serveur MCP d'exemple](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server), définissez plutôt `routes` sur `echo: http://hello-mcp:9000`. Générez le rendu du chart et examinez la sortie conformément aux pratiques de validation de votre organisation : ```bash helm template mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.0.2 \ -n mcp-tunnel \ -f values.yaml > rendered.yaml ``` ```bash helm install mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.0.2 \ --namespace mcp-tunnel --create-namespace \ -f values.yaml ``` Le composant de configuration s'exécute en tant que Job de hook pre-install Helm, donc `helm install` reste bloqué jusqu'à ce qu'il se termine. En cas de succès, Helm supprime automatiquement le Job. Si `helm install` échoue avec une erreur de hook, consultez [Échecs d'authentification du composant de configuration](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/troubleshooting#setup-component-authentication-failures). Lorsque `tunnel.id` est vide, le composant de configuration crée le tunnel dans l'espace de travail ciblé par votre règle de fédération (l'espace de travail par défaut de l'organisation, sauf si vous définissez `api.wif.workspaceId`) et stocke son ID et son domaine dans le Secret `mcp-tunnel`. Trouvez le domaine dont vous aurez besoin pour la [vérification](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/deploy-helm#verify-the-deployment) sur la page de détail du tunnel, que vous ouvrez depuis la page [MCP tunnels](https://platform.claude.com/settings/workspaces/default/mcp-tunnels) (`platform.claude.com/settings/workspaces/default/mcp-tunnels`) dans la Console. Dans le sélecteur d'espace de travail de la barre latérale, sélectionnez l'espace de travail qui contient le tunnel. Vous pouvez également lire le domaine depuis le Secret : ```bash kubectl -n mcp-tunnel get secret mcp-tunnel \ -o jsonpath='{.data.tunnel-domain}' | base64 -d ``` La réexécution du composant de configuration (lors des [mises à niveau](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/deploy-helm#upgrades) ou de la [rotation du jeton](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/deploy-helm#rotate-the-tunnel-token)) réutilise l'ID de tunnel stocké dans ce Secret ; elle ne crée jamais de second tunnel. Les valeurs `api.wif.*` sont des identifiants, et non des secrets ; les stocker dans les Secrets d'historique de release Helm ne présente donc pas de risque. Les données sensibles au repos sont le Secret `mcp-tunnel` créé par le composant de configuration, qui contient le jeton de tunnel et les clés privées TLS. Appliquez à cet espace de noms les pratiques standard de votre organisation en matière de protection des Secrets Kubernetes. Dans ce mode (`setup.enabled: false`), le chart n'effectue aucun appel API ; le composant de configuration ne s'exécute pas et il n'y a pas de CronJob cert-renew. Utilisez cette voie si vous préférez ne pas configurer Workload Identity Federation. [Créez le tunnel](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/console#create-a-tunnel) et [obtenez le jeton de tunnel depuis la Console](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/console#get-the-connection-details). Notez le domaine du tunnel depuis la page de détail. Vous le définirez comme `gateway.config.tunnel_domain`. Le proxy écoute en WebSocket non chiffré, avec le [TLS interne](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/concepts#components) (inner TLS) transporté à l'intérieur de ce flux à l'aide du certificat que vous générez ici. Le SAN du certificat serveur doit inclure `*.` conformément aux [exigences relatives aux certificats](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/reference#certificate-requirements). ```bash export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE mkdir -p mcp-tunnel/data cd mcp-tunnel # CA auto-signée. Extensions explicites pour satisfaire aux exigences # du certificat quels que soient les défauts openssl.cnf de la distribution. openssl req -x509 -newkey rsa:2048 -nodes \ -keyout data/ca.key -out data/ca.crt \ -days 3650 -subj "/CN=mcp-tunnel-ca" \ -addext "basicConstraints=critical,CA:TRUE" \ -addext "keyUsage=critical,keyCertSign,cRLSign" \ -addext "subjectKeyIdentifier=hash" # Fichier d'extensions pour le certificat serveur. Utiliser -extfile (au lieu de # -copy_extensions, réservé à OpenSSL 3.0+) garantit le fonctionnement sur # OpenSSL 1.1.x. cat > data/tls.ext < Le chart lit des clés spécifiques ; les noms des Secrets sont configurables, mais les clés ne le sont pas. La commande de création d'espace de noms suivante est sans effet si l'espace de noms existe déjà (par exemple, à la suite de l'étape du [serveur MCP d'exemple](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server)). ```bash kubectl create namespace mcp-tunnel --dry-run=client -o yaml | kubectl apply -f - kubectl -n mcp-tunnel create secret generic mcp-tunnel-token \ --from-literal=tunnel-token='eyJ...' kubectl -n mcp-tunnel create secret generic mcp-tunnel-cert \ --from-file=tls.crt=data/tls.crt \ --from-file=tls.key=data/tls.key ``` ```bash helm show values \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.0.2 > values.yaml ``` Modifiez `values.yaml` et définissez les clés suivantes : ```yaml values.yaml setup: enabled: false external: tunnelTokenSecretName: mcp-tunnel-token # must contain key: tunnel-token serverCertSecretName: mcp-tunnel-cert # must contain keys: tls.crt, tls.key gateway: config: # Required when setup.enabled is false. Replace the placeholder with # the $TUNNEL_DOMAIN value you exported earlier. When setup.enabled # is true the chart injects this from the Secret as a -tunnel-domain # flag instead. tunnel_domain: YOUR_TUNNEL_DOMAIN_HERE routes: docs: http://docs-mcp.internal:8080 search: http://search-mcp.internal:8080 ``` Certaines distributions Kubernetes managées allouent le CIDR des Services en dehors des plages privées standard ; si vos routes ciblent des Services internes au cluster, ajoutez ici `gateway.config.upstream.allowed_ips` conformément à la section [Validation des IP en amont](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/troubleshooting#upstream-ip-validation). Si vous utilisez le [serveur MCP d'exemple](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server), définissez plutôt `routes` sur `echo: http://hello-mcp:9000`. ```bash helm template mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.0.2 \ -n mcp-tunnel \ -f values.yaml > rendered.yaml ``` ```bash helm install mcp-tunnel \ oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \ --version 2.0.2 \ --namespace mcp-tunnel --create-namespace \ -f values.yaml ``` ## Vérifier le déploiement Vérifiez de bout en bout du côté d'Anthropic : utilisez `https://./` dans une session Managed Agent ou une requête à l'API Messages, où `` est une clé de `gateway.config.routes` et `` est le chemin sur lequel le serveur MCP en amont répond. Avec le [serveur MCP d'exemple](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server), il s'agit de `https://echo./mcp`. Consultez [Utiliser les serveurs MCP tunnelisés](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers) 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](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/troubleshooting). ## 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](https://platform.claude.com/docs/fr/agents-and-tools/mcp-tunnels/reference#proxy-configuration) 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](https://platform.claude.com/docs/fr/manage-claude/wif-providers/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 : ```bash 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 ``` Maintenez un `values.yaml` complet plutôt que de vous appuyer sur `--reuse-values`. Le comportement de fusion profonde de Helm peut échouer silencieusement à supprimer les routes effacées. ### 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é : ```bash 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` : ```bash 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 ``` Cliquer sur **Rotate token** invalide immédiatement le jeton actuel. Tant que le Secret n'est pas mis à jour et que le déploiement progressif n'est pas terminé, tout pod qui redémarre avec l'ancien jeton (éviction, drainage de nœud, OOM) ne peut pas se reconnecter. Mettez à jour le Secret rapidement après la rotation ; pour des exigences de disponibilité plus strictes, utilisez l'accès programmatique afin que le chart gère la rotation de manière atomique. ### 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) : ```bash 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 Attachez un serveur MCP en amont à un Managed Agent ou à l'API Messages. Conseils de durcissement, rotation des identifiants et réponse aux compromissions. Diagnostiquez les problèmes de connectivité, de TLS et de routage.