Déployer des tunnels MCP avec Helm

Le composant de configuration échange le jeton 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, et enregistre la CA auprès d'Anthropic. Un CronJob quotidien renouvelle le certificat serveur si nécessaire, de sorte que vous ne manipulez aucun secret à la main.

1. 1

   Configurer Workload Identity Federation pour le cluster

   Suivez Utiliser WIF avec 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 le namespace 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 <release> ... | grep -A2 'kind: ServiceAccount' pour le confirmer avant de créer la règle. La suite de ce guide suppose le nom de release mcp-tunnel dans le namespace mcp-tunnel, où le ServiceAccount est mcp-tunnel-setup.

   Champ	Valeur
   Sujet	system:serviceaccount:mcp-tunnel:mcp-tunnel-setup
   Audience	api.anthropic.com (la valeur par défaut du chart ; sans schéma)
   Portée	workspace:manage_tunnels

   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 (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.

2. 2

   Récupérer les valeurs par défaut

   helm show values \
     oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
     --version 2.1.0 > values.yaml

   
3. 3

   Configurer l'attachement au tunnel et les routes

   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 :

   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.<your-tunnel-domain> et search.<your-tunnel-domain>. Certaines distributions Kubernetes gérées allouent le CIDR des Services en dehors des plages privées standard ; si vos routes ciblent des Services internes au cluster, ajoutez gateway.config.upstream.allowed_ips ici comme décrit dans Validation des IP en amont.

4. 4

   Examiner les manifestes générés

   Générez le rendu du chart et examinez le résultat conformément aux pratiques de vérification de votre organisation :

   helm template mcp-tunnel \
     oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
     --version 2.1.0 \
     -n mcp-tunnel \
     -f values.yaml > rendered.yaml

   
5. 5

   Installer

   helm install mcp-tunnel \
     oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
     --version 2.1.0 \
     --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.

   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 sur la page de détails du tunnel, que vous ouvrez depuis la page Tunnels MCP (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 :

   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 ou de la rotation du jeton) réutilise l'ID de tunnel stocké dans ce Secret ; elle ne crée jamais de second tunnel.

Dans ce mode (setup.enabled: false), le chart n'effectue aucun appel d'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.

1. 1

   Obtenir le jeton et le domaine du tunnel

   Créez le tunnel et obtenez le jeton de tunnel depuis la Console.

2. 2

   Générer une CA et un certificat serveur

   Le proxy écoute en WebSocket simple, le TLS interne étant transporté à l'intérieur de ce flux à l'aide du certificat que vous générez ici. Le SAN du certificat serveur doit inclure *.<tunnel-domain> comme décrit dans les exigences relatives aux certificats.

   export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE
   mkdir -p mcp-tunnel/data
   cd mcp-tunnel
   
   # CA auto-signée. Extensions explicites pour satisfaire les exigences du certificat
   # quelles que soient les valeurs par défaut du 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, disponible uniquement à partir d'OpenSSL 3.0) assure la compatibilité avec
   # OpenSSL 1.1.x.
   cat > data/tls.ext <<EOF
   subjectAltName = DNS:${TUNNEL_DOMAIN},DNS:*.${TUNNEL_DOMAIN}
   authorityKeyIdentifier = keyid,issuer
   extendedKeyUsage = serverAuth
   EOF
   
   # Certificat serveur signé par la CA
   openssl req -newkey rsa:2048 -nodes \
     -keyout 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

   

   Enregistrez data/ca.crt dans la Console. Conservez data/ca.key dans un endroit durable et sécurisé ; vous en aurez besoin pour signer un nouveau certificat serveur lors du renouvellement.

3. 3

   Créer les deux Secrets

   Le chart lit des clés spécifiques ; les noms des Secrets sont configurables, mais pas les clés. La commande de création de namespace suivante n'a aucun effet si le namespace existe déjà (par exemple, depuis l'étape du serveur MCP d'exemple).

   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

   
4. 4

   Récupérer les valeurs par défaut

   helm show values \
     oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
     --version 2.1.0 > values.yaml

   
5. 5

   Configurer les valeurs pour le provisionnement manuel

   Modifiez values.yaml et définissez les clés suivantes :

   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 gérées allouent le CIDR des Services en dehors des plages privées standard ; si vos routes ciblent des Services internes au cluster, ajoutez gateway.config.upstream.allowed_ips ici comme décrit dans Validation des IP en amont.

6. 6

   Examiner les manifestes générés

   helm template mcp-tunnel \
     oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
     --version 2.1.0 \
     -n mcp-tunnel \
     -f values.yaml > rendered.yaml

   
7. 7

   Installer

   helm install mcp-tunnel \
     oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
     --version 2.1.0 \
     --namespace mcp-tunnel --create-namespace \
     -f values.yaml

   