Passer au contenu principal

Tunnels MCP

Qu'est-ce que c'est ?

Connectez Claude de manière sécurisée aux serveurs MCP s'exécutant dans votre réseau privé sans ouvrir de ports entrants ni exposer les services à Internet. MCP Tunnels est actuellement en version bêta privée et s'appuie sur le service Tunnel de Cloudflare.

Fonctionnement

MCP Tunnels crée une connexion entre Claude et vos serveurs MCP internes qui est chiffrée en transit avec plusieurs couches de sécurité.

Lorsque Claude doit accéder à un serveur MCP dans votre réseau privé, la demande transite par un tunnel sécurisé. Vous déployez deux composants de votre côté :

  • cloudflared (agent tunnel de Cloudflare)

  • MCP Gateway (fourni par Anthropic)

Cloudflared établit une connexion sortante uniquement vers le réseau périphérique de Cloudflare. Aucun port entrant n'a besoin d'être ouvert dans votre pare-feu. MCP Gateway termine une couche TLS interne, valide les adresses IP en amont pour prévenir les attaques SSRF, et achemine chaque demande vers le serveur MCP approprié en fonction du sous-domaine.

La connexion est sécurisée par trois couches indépendantes : mTLS externe entre Anthropic et Cloudflare (avec validation d'adresse IP), TLS interne qui chiffre les charges utiles de bout en bout depuis le backend d'Anthropic vers votre passerelle (conçu pour que Cloudflare n'ait pas accès aux charges utiles MCP), et authentification OAuth au niveau de la couche application sur chaque serveur MCP.

Ce que vous déployez

cloudflared

Agent tunnel de Cloudflare. Établit des connexions sortantes uniquement — aucun port entrant nécessaire.

MCP Gateway

Composant fourni par Anthropic qui termine la TLS interne, valide les adresses IP, et achemine les demandes vers vos serveurs MCP.

Propriétés de sécurité clés

  • Aucun port entrant requis. cloudflared établit uniquement des connexions sortantes — votre pare-feu reste fermé.

  • Chiffrement de bout en bout. Le trafic est chiffré en transit depuis le backend d'Anthropic vers votre passerelle. Les charges utiles MCP ne peuvent pas être lues par Cloudflare.

  • Défense en profondeur. Plusieurs couches d'authentification : mTLS, TLS interne, et OAuth au niveau de la couche application.

  • Protection SSRF. La passerelle valide les adresses IP en amont pour aider à prévenir les attaques par usurpation de demande.

Ce guide fournit des déploiements de référence via Helm (pour Kubernetes) et Docker Compose. Vous êtes responsable de les adapter pour répondre aux exigences de sécurité de votre organisation.

Responsabilité partagée

Maintenir ce système sécurisé est une responsabilité partagée entre Anthropic et votre organisation.

Anthropic est responsable de :

  • S'assurer que seul Anthropic peut accéder aux tunnels

  • Valider votre certificat CA avant de se connecter à votre passerelle

  • S'assurer que Claude envoie uniquement des demandes aux tunnels appartenant à votre organisation

Vous êtes responsable de :

  • Suivre les conseils de ce document et tout conseil ultérieur

  • Sécuriser le jeton de tunnel et les clés privées TLS

  • Configurer vos serveurs MCP pour utiliser l'authentification OAuth comme décrit dans la spécification MCP

  • Restreindre l'accès à vos hôtes de passerelle et serveurs MCP au personnel approprié

  • Notifier Anthropic si vous soupçonnez que le système a été compromis (voir Répondre à une violation suspectée)

⚠️ Risque d'identifiants. Si un attaquant obtient votre jeton de tunnel et l'une de vos clés privées TLS, il pourrait usurper l'identité de votre passerelle et lire les charges utiles des demandes MCP, y compris les jetons OAuth. Protégez ces identifiants selon les exigences de sécurité de votre organisation — y compris les permissions de fichiers, le chiffrement au repos, et la gestion des secrets.

Prérequis

  • Une cible de déploiement — un cluster Kubernetes (pour Helm) ou une machine virtuelle avec Docker et Docker Compose.

  • Un jeton API Anthropic pour l'API Tunnels — générez-en un à partir de claude.ai → Organization Settings → Connectors → Tunnels API. La configuration utilise ce jeton pour provisionner le tunnel et enregistrer votre certificat CA. La passerelle n'en a pas besoin à l'exécution. Révoquez-le une fois la configuration terminée.

  • Accès réseau — connectivité sortante selon le tableau ci-dessous.

  • Serveurs MCP — un ou plusieurs serveurs MCP s'exécutant dans votre réseau privé que la passerelle peut atteindre.

Exigences réseau

Composant

Destination

Objectif

Configuration (une seule fois)

api.anthropic.com:443

(port 443)

Provisionnement du tunnel

cloudflared

Réseau périphérique Cloudflare, port 7844 TCP/UDP (198.41.192.0/19, 2606:4700:a0::/44)

Connexion tunnel

Passerelle MCP

Vos serveurs MCP

Trafic en amont

Consultez la documentation du pare-feu tunnel de Cloudflare pour la liste d'adresses IP faisant autorité. Les utilisateurs de Helm peuvent appliquer cette restriction de sortie en activant la valeur networkPolicy du graphique.

Choisissez votre méthode de déploiement

Les tunnels MCP peuvent être déployés via Helm (Kubernetes) ou Docker Compose. Choisissez la méthode qui correspond à votre infrastructure.

⎈ Helm / Kubernetes

Recommandé pour la plupart des clients. Automatise l'approvisionnement des tunnels et le renouvellement des certificats. Stocke les identifiants en tant que Secrets.

🐳 Docker Compose

Pour les déploiements sur un seul hôte ou sur machine virtuelle.

Déploiement Helm / Kubernetes

1. Récupérez les valeurs du graphique

Téléchargez le fichier de valeurs par défaut. Il inclut des commentaires expliquant chaque champ.

Shell

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

2. Configurez vos routes

Modifiez values.yaml et ajoutez au moins une route sous gateway.config.routes. Chaque route mappe un préfixe de sous-domaine à une URL de serveur MCP en amont.

3. Examinez les manifestes rendus

Rendez le graphique avec un jeton d'espace réservé pour inspecter les ressources Kubernetes avant l'installation. Le graphique nécessite api.token pour le rendu, mais helm template n'appelle pas l'API.

Shell

helm template mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 \
  -n mcp-tunnel \
  -f values.yaml \
  --set api.token=placeholder > rendered.yaml

Examinez rendered.yaml selon les pratiques de votre organisation pour l'examen des manifestes tiers.

4. Installez le graphique

Stockez votre jeton API dans une variable d'environnement, puis installez. Un espace de noms dédié est recommandé pour l'isolation.

Shell

# Paste your API token (input is hidden)
read -rs API_TOKEN && export API_TOKEN

helm install mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 \
  --namespace mcp-tunnel --create-namespace \
  -f values.yaml \
  --set api.token="$API_TOKEN"

⚠️ Important : Révoquez le jeton API une fois l'installation terminée. Passer le jeton via --set le maintient hors de votre fichier de valeurs, mais Helm l'enregistre toujours dans l'historique des versions (sh.helm.release.v1.* Secrets). Les Secrets Kubernetes ne sont pas chiffrés au repos par défaut, donc le jeton reste récupérable à partir du cluster jusqu'à ce que vous le révoquiez.

5. Récupérez votre domaine de tunnel

Le Job de configuration écrit le domaine du tunnel dans un Secret. Vous en aurez besoin pour configurer les serveurs MCP dans Claude.

Shell

kubectl get secret mcp-tunnel -n mcp-tunnel \
  -o jsonpath='{.data.tunnel-domain}' | base64 -d

Une fois le tunnel opérationnel, connectez-vous à Claude.

Facultatif : Activez NetworkPolicy

Définissez networkPolicy.enabled: true dans votre fichier de valeurs pour restreindre la sortie du pod tunnel au niveau du réseau. Configurez networkPolicy.mcpServers avec des sélecteurs d'étiquettes de pod ou des plages CIDR pour vos serveurs MCP en amont. La politique inclut déjà des règles de sortie pour que cloudflared atteigne le réseau périphérique de Cloudflare. Votre CNI de cluster doit prendre en charge NetworkPolicy—consultez le fichier de valeurs pour un exemple.

Facultatif : Configuration de la passerelle

Les champs sous gateway.config.* sont transmis au fichier de configuration de la passerelle. Consultez Appendice : Configuration de la passerelle pour la liste complète. Les ajustements courants incluent upstream.allowed_ips, log_level et upstream.tls pour les routes https://. Pour monter des fichiers supplémentaires référencés par la configuration (comme un bundle CA pour upstream.tls.ca_file), utilisez gateway.extraVolumes et gateway.extraVolumeMounts.

Mises à jour

Spécifiez toujours --version sur helm upgrade. Sans cela, Helm récupère la dernière version du graphique à partir du registre, ce qui peut ne pas être ce que vous avez examiné.

Pour les modifications de configuration (routes, réplicas, NetworkPolicy, etc.), aucun jeton API n'est nécessaire. Le Job de configuration est ignoré lors des mises à jour sauf si vous transmettez api.token :

Shell

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 \
  -n mcp-tunnel \
  -f values.yaml

Pour la rotation du jeton de tunnel, incrémentez tunnel.tokenVersion dans votre fichier de valeurs, générez un jeton API frais et mettez à jour :

Shell

# Paste your API token (input is hidden)
read -rs API_TOKEN && export API_TOKEN

helm upgrade mcp-tunnel \
  oci://us-docker.pkg.dev/anthropic-public-registry/charts/mcp-tunnel \
  --version 0.1.0 \
  -n mcp-tunnel \
  -f values.yaml \
  --set api.token="$API_TOKEN"

Révoquez le jeton API une fois la mise à jour terminée.

Maintenez un fichier de valeurs complet plutôt que de vous fier à --reuse-values. Helm fusionne profondément les champs de carte, donc la suppression d'une route avec --reuse-values échoue silencieusement.

Utilisation de helm template avec kubectl ou kustomize

Si vous préférez rendre les manifestes et les appliquer vous-même (via kubectl apply ou les superpositions kustomize), utilisez le mode externe (setup.enabled: false). Approvisionnez le tunnel séparément (consultez Appendice : API Tunnels) et fournissez les identifiants en tant que Secrets pré-créés référencés par external.tunnelTokenSecretName et external.serverCertSecretName. Si vous émettez vos propres certificats au lieu d'utiliser le binaire de configuration, consultez Appendice : Exigences en matière de certificats.

Déploiement Docker Compose

1. Préparez le répertoire de déploiement

Shell

mkdir -p mcp-gateway/{config,tunnel-data}
cd mcp-gateway
sudo chown 65532:65532 tunnel-data

Le chown permet au conteneur (qui s'exécute en tant qu'UID 65532) d'écrire dans le répertoire monté en liaison.

2. Créez docker-compose.yaml

YAML

services:
  # One-time provisioning. Run with: docker compose run --rm setup
  setup:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-gateway@sha256:62ddf0897778c80997ca789189a8a0bd63df241659d661ff9d5b0e06b5ee1dcd
    entrypoint: ["/setup"]
    command:
      - init
      - --api-url=https://api.anthropic.com
      - --output=dir:/data
      - --token-version=1
    environment:
      - API_TOKEN
    volumes:
      - ./tunnel-data:/data
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    profiles: ["setup"]

  cloudflared:
    # Verify digest at https://hub.docker.com/r/cloudflare/cloudflared/tags
    image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0
    command: tunnel --no-autoupdate --config /etc/cloudflared/config.yaml run
    environment:
      - TUNNEL_TOKEN
    volumes:
      - ./config/cloudflared-config.yaml:/etc/cloudflared/config.yaml:ro
    restart: unless-stopped
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    stop_grace_period: 30s
    logging:
      options:
        max-size: "10m"
        max-file: "3"

  mcp-gateway:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-gateway@sha256:62ddf0897778c80997ca789189a8a0bd63df241659d661ff9d5b0e06b5ee1dcd
    volumes:
      - ./config/mcp-gateway.yaml:/etc/mcp-gateway/config.yaml:ro
      - ./tunnel-data:/data:ro
    restart: unless-stopped
    user: "65532:65532"
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    # Should match shutdown_timeout in mcp-gateway config
    stop_grace_period: 30s
    logging:
      options:
        max-size: "10m"
        max-file: "3"

Mesures de sécurité : exécution sans privilèges (UID 65532), système de fichiers en lecture seule, pas d'escalade de privilèges, toutes les capacités Linux supprimées, épinglage d'image par condensé SHA256.

3. Provisionner le tunnel

Shell

# Paste your API token (input is hidden)
read -rs API_TOKEN && export API_TOKEN

docker compose run --rm setup

La commande de configuration crée un tunnel via l'API Tunnels, génère un certificat CA et serveur, enregistre le CA auprès d'Anthropic, et écrit tous les résultats dans ./tunnel-data/.

Récupérez votre domaine de tunnel pour l'étape suivante :

Shell

sudo cat tunnel-data/tunnel-domain

⚠️ Important : révoquez le jeton API avant de continuer.

4. Configurer la passerelle

Créez config/mcp-gateway.yaml :

YAML

listen_addr: ":8080"
log_level: info
shutdown_timeout: 30s

# Your tunnel domain from Step 3
tunnel_domain: abcd1234.tunnel.anthropic.com

tls:
  cert_file: /data/tls.crt
  key_file: /data/tls.key

routes:
  # Replace with your actual MCP servers.
  # With tunnel_domain set, keys are subdomain prefixes.
  docs: http://docs-mcp.internal:8080
  search: http://search-mcp.internal:8080

upstream:
  allowed_ips:
    - 10.0.0.0/8

Consultez Appendice : Configuration de la passerelle pour tous les champs disponibles.

Créez config/cloudflared-config.yaml :

YAML

ingress:
  - service: http://mcp-gateway:8080

5. Déployer

Shell

export TUNNEL_TOKEN=$(sudo cat tunnel-data/tunnel-token)
docker compose up -d
docker compose logs -f

Structure des répertoires :

mcp-gateway/
├── docker-compose.yaml
├── config/
│   ├── cloudflared-config.yaml
│   └── mcp-gateway.yaml
└── tunnel-data/
    ├── tunnel-id
    ├── tunnel-domain
    ├── tunnel-token
    ├── token-version
    ├── ca.crt
    ├── ca.key
    ├── tls.crt
    └── tls.key

Envisagez de déplacer la clé privée CA et le jeton de tunnel vers un stockage sécurisé.

Pour les déploiements multi-VM : copiez le répertoire mcp-gateway/ sur chaque hôte. Le même jeton de tunnel et les mêmes certificats fonctionnent sur tous les réplicas.

Une fois le tunnel opérationnel, connectez-vous à Claude.

Renouvellement de certificat (Compose)

Le certificat serveur a une validité de 90 jours. Renouvelez avant l'expiration :

Shell

docker compose run --rm setup renew-cert --output=dir:/data

La passerelle interroge le fichier de certificat toutes les 30 secondes et le recharge automatiquement en cas de modification. Consultez Appendice : Référence CLI de configuration pour les drapeaux qui rendent cette commande sûre à exécuter selon un calendrier.

Rotation du jeton de tunnel (Compose)

Modifiez docker-compose.yaml pour incrémenter --token-version, puis réexécutez la configuration avec un nouveau jeton API :

# Paste your API token (input is hidden)
read -rs API_TOKEN && export API_TOKEN

docker compose run --rm setup

export TUNNEL_TOKEN=$(sudo cat tunnel-data/tunnel-token)
docker compose up -d cloudflared

Révoquez le jeton API une fois la rotation terminée.

Connectez-vous à Claude

Une fois le tunnel en cours d'exécution, enregistrez vos serveurs MCP dans Claude pour qu'ils soient disponibles pour les utilisateurs.

1. Ajouter des serveurs MCP

Un administrateur d'organisation accède à Organization Settings → Connectors → Add → Custom → Web dans claude.ai.

Entrez chaque serveur MCP en utilisant son nom d'hôte de tunnel. Par exemple, docs.abcd1234.tunnel.anthropic.com. Le préfixe de sous-domaine correspond à la clé de route de votre configuration de passerelle.

2. Les utilisateurs se connectent

Les utilisateurs individuels accèdent à Settings → Connectors et cliquent sur Connect pour chaque serveur MCP qu'ils souhaitent utiliser.

Ajouter d'autres serveurs plus tard ? Ajoutez une nouvelle route à votre configuration, appliquez la modification (helm upgrade, ou docker compose restart mcp-gateway), et enregistrez le nouveau nom d'hôte dans Claude. Aucune modification de certificat ou cloudflared nécessaire. Le certificat générique couvre tous les sous-domaines.

Meilleures pratiques de sécurité

  1. Exigez OAuth sur vos serveurs MCP. Les couches tunnel et TLS protègent le transport, mais si elles sont jamais compromises, OAuth au niveau de l'application empêche toujours l'invocation d'outils non autorisée. Configurez chaque serveur MCP pour exiger l'authentification OAuth comme décrit dans la spécification MCP.

  2. Activez SSO pour votre organisation claude.ai. Les jetons de tunnel sont générés à partir de la console claude.ai. Avec SSO appliqué, les contrôles de session de votre fournisseur d'identité régissent les sessions d'administrateur.

  3. Limitez allowed_ips. Utilisez les plus petites plages CIDR qui couvrent vos serveurs MCP.

  4. Surveillez les journaux. Configurez les alertes sur les avertissements, les erreurs et les modèles inhabituels.

  5. Faites tourner les identifiants. Renouvelez les certificats selon un calendrier régulier, ou immédiatement si une compromission est suspectée.

  6. Maintenez les images à jour. Appliquez les mises à jour de passerelle rapidement. Épinglez les images par résumé SHA256.

  7. Limitez l'accès réseau. La passerelle et cloudflared ne doivent avoir que l'accès réseau requis.

  8. Limitez la portée du serveur MCP. Les serveurs MCP ne doivent exposer que les fonctionnalités nécessaires.

  9. Protégez les identifiants au repos. Appliquez les autorisations de fichier appropriées, le chiffrement au repos et la gestion des secrets au répertoire tunnel-data/ (Compose) ou au Secret des identifiants (Helm).

Répondre à une violation suspectée

Si vous suspectez que vos identifiants de tunnel, clés TLS ou un autre aspect du système a été compromis :

  1. Arrêtez le déploiement immédiatement (helm uninstall ou docker compose down --timeout 0)

  2. Supprimez les serveurs MCP de Claude (Organization Settings → Connectors)

  3. Archivez le tunnel via l'API (voir Teardown, étape 3)

  4. Contactez Anthropic pour qu'ils puissent enquêter

  5. Faites tourner les identifiants — reprovisionnez un nouveau tunnel, renouvelez les jetons OAuth sur vos serveurs MCP

  6. Examinez les journaux avant de restaurer le service

Dépannage

Échecs de validation IP

« Validation IP échouée » dans les journaux de passerelle signifie que l'amont s'est résolu en une adresse IP en dehors de allowed_ips. Vérifiez l'adresse IP résolue :

Shell

dig +short docs-mcp.internal

Si l'adresse IP est légitime, mettez à jour allowed_ips dans votre configuration de passerelle pour inclure la plage CIDR correcte.

Tunnel non connecté

Vérifiez les journaux cloudflared pour les erreurs. Causes courantes :

  • Jeton de tunnel invalide

  • Pare-feu bloquant le port 7844 TCP/UDP sortant vers l'edge Cloudflare

Vérifiez la connectivité sortante vers les plages IP de Cloudflare : 198.41.192.0/19 et 2606:4700:a0::/44.

Avertissements de taille de tampon UDP

cloudflared peut enregistrer failed to sufficiently increase receive buffer size. Il s'agit d'un problème d'ajustement du transport QUIC — consultez la documentation du tampon UDP quic-go pour l'ajuster.

Erreurs de certificat

Si la négociation TLS échoue, vérifiez que :

  • Le certificat du serveur n'a pas expiré (validité de 90 jours)

  • Le SAN du certificat correspond à *.<tunnel-domain>

  • Le certificat CA est enregistré auprès d'Anthropic via l'API

  • Pour Compose, les fichiers de certificat sont lisibles par UID 65532

Routage OAuth via le tunnel (serveur d'authentification derrière une liste blanche IP)

Problème : Votre serveur d'authentification se trouve derrière une liste blanche d'adresses IP source. Le backend de Claude doit le joindre pour la découverte OAuth, l'enregistrement du client et l'échange de jetons, mais vous préférez ne pas ajouter les plages d'adresses IP de sortie d'Anthropic à la liste blanche.

Solution : configuration de point de terminaison divisé. Routez les appels OAuth backend-to-backend via le tunnel. Conservez le point de terminaison /authorize côté navigateur sur votre nom d'hôte existant en liste blanche. Cela fonctionne car Claude lit l'authorization_endpoint à partir de vos métadonnées de découverte et redirige le navigateur de l'utilisateur vers celui-ci. Il n'a pas besoin d'accéder à cette URL lui-même.

Étape 1 : Ajouter une route de passerelle pour votre serveur d'authentification

YAML — mcp-gateway.yaml

routes:
  mcp: http://your-mcp-server:8080
  auth: http://your-auth-server:8080

Étape 2 : Servir les métadonnées de découverte de point de terminaison divisé

Le /.well-known/oauth-authorization-server de votre serveur d'authentification doit retourner :

JSON

{
  "issuer": "https://auth.<tunnel-id>.tunnel.anthropic.com",
  "authorization_endpoint": "https://<your-allowlisted-host>/authorize",
  "token_endpoint": "https://auth.<tunnel-id>.tunnel.anthropic.com/token",
  "registration_endpoint": "https://auth.<tunnel-id>.tunnel.anthropic.com/register",
  "code_challenge_methods_supported": ["S256"]
}

Seul authorization_endpoint pointe vers votre nom d'hôte existant. Tout le reste utilise l'URL du tunnel.

Étape 3 : Pointez votre serveur MCP vers l'émetteur du tunnel

Le /.well-known/oauth-protected-resource de votre serveur MCP :

JSON

{
  "resource": "https://mcp.<tunnel-id>.tunnel.anthropic.com",
  "authorization_servers": [
    "https://auth.<tunnel-id>.tunnel.anthropic.com"
  ]
}

Démantèlement

Comment désactiver un tunnel quand il n'est plus nécessaire.

1. Obtenir l'ID du tunnel

Helm

TUNNEL_ID=$(kubectl get secret mcp-tunnel -n mcp-tunnel \
  -o jsonpath='{.data.tunnel-id}' | base64 -d)

Compose

TUNNEL_ID=$(sudo cat tunnel-data/tunnel-id)

2. Arrêter le déploiement

Helm : helm uninstall mcp-tunnel -n mcp-tunnel (remarque : le Secret des identifiants a été créé par le Job de configuration, pas par Helm, il survit donc à la désinstallation)
​Compose : docker compose down

3. Archiver le tunnel

Générez d'abord un jeton API frais et révoquez-le une fois terminé.

Shell

read -rs API_TOKEN && export API_TOKEN

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/archive" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

4. Supprimer les identifiants stockés

Helm : kubectl delete secret mcp-tunnel -n mcp-tunnel
​Compose : sudo rm -rf tunnel-data

Obtenir de l'aide

Contactez votre équipe de compte Anthropic pour obtenir de l'aide.

Annexe : Configuration de la passerelle

La passerelle lit sa configuration à partir d'un fichier YAML. Dans Docker Compose, vous écrivez ce fichier directement sous config/mcp-gateway.yaml. Dans Helm, définissez ces champs sous gateway.config.* dans votre fichier de valeurs — le graphique gère listen_addr, tls et tunnel_domain pour vous.

Champ

Description

Par défaut

listen_addr

Adresse et port d'écoute

Requis

log_level

Verbosité de la journalisation : debug, info, warn, error

info

shutdown_timeout

Temps d'attente pour les requêtes en cours lors de l'arrêt gracieux

30s

tunnel_domain

Domaine de base pour la résolution des routes avec préfixe

Aucun

tls.cert_file

Chemin du certificat TLS

Requis

tls.key_file

Chemin de la clé privée TLS

Requis

routes

Mappage du nom d'hôte (ou préfixe) vers l'URL en amont

Requis

upstream.allowed_ips

Plages CIDR auxquelles la passerelle peut se connecter

Plages privées RFC 1918

upstream.disable_ip_validation

Désactiver complètement la validation des adresses IP

false

upstream.tls.ca_file

Paquet CA pour valider le TLS en amont

Aucun

upstream.tls.include_system_cas

Faire confiance au paquet CA système pour le TLS en amont

false

Pour les routes https://, définissez au moins l'une des options upstream.tls.ca_file ou upstream.tls.include_system_cas.

Annexe : API Tunnels

Pour les flux de provisionnement personnalisés, vous pouvez appeler directement l'API Tunnels. Toutes les requêtes nécessitent ces en-têtes :

Shell

-H "Authorization: Bearer $API_TOKEN"
-H "anthropic-version: 2023-06-01"
-H "anthropic-beta: mcp-tunnels-2026-02-24"

Créer un tunnel :

curl -X POST https://api.anthropic.com/v1/tunnels \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24" \
  -H "Content-Type: application/json" \
  -d '{}'

Lister les tunnels :

curl https://api.anthropic.com/v1/tunnels \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Enregistrer un certificat CA :

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/certificates" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24" \
  -H "Content-Type: application/json" \
  -d "{\"ca_certificate_pem\": $(jq -Rs . < ca.crt)}"

Consultez Annexe : Exigences relatives aux certificats pour connaître ce que les certificats CA et serveur doivent contenir.

Lister les certificats CA :

curl "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/certificates" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Révoquer un certificat CA :

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/certificates/${CERT_ID}/revoke" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Révéler le jeton du tunnel :

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/reveal_token" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Faire tourner le jeton du tunnel :

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/rotate_token" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Archiver un tunnel :

curl -X POST "https://api.anthropic.com/v1/tunnels/${TUNNEL_ID}/archive" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-tunnels-2026-02-24"

Annexe : Exigences relatives aux certificats

Si vous utilisez le binaire de configuration (setup init / setup renew-cert), il génère automatiquement des certificats conformes et vous pouvez ignorer cette section. Ces exigences s'appliquent si vous émettez des certificats via votre propre PKI.

Certificat CA — téléchargé via POST /v1/tunnels/{id}/certificates. Un tunnel peut contenir au maximum deux certificats CA actifs à la fois, ce qui permet une rotation sans interruption de service.

  • Codé en PEM, certificat unique, au maximum 8 KB

  • Extension BasicConstraints avec CA:TRUE, marquée critique

  • Extension SubjectKeyIdentifier présente

  • KeyUsage inclut keyCertSign

  • Dans la période de validité

  • RSA 2048 bits ou plus, ou ECDSA P-256 ou plus ; signature SHA-256 ou plus forte

Certificat serveur — présenté par la passerelle lors de la négociation TLS interne. Non téléchargé vers Anthropic.

  • Signé directement par une CA enregistrée sur le tunnel

  • Extension AuthorityKeyIdentifier présente, correspondant au SubjectKeyIdentifier de la CA

  • SAN inclut un nom DNS correspondant à <route>.<tunnel-domain> (un wildcard *.<tunnel-domain> couvre tous les itinéraires)

  • Si une extension ExtendedKeyUsage est présente, elle inclut serverAuth

  • Dans la période de validité

  • RSA 2048 bits ou plus, ou ECDSA P-256 ou plus ; signature SHA-256 ou plus forte

Référence : le binaire de configuration génère une CA ECDSA P-256 (validité 5 ans) et un certificat serveur RSA 4096 bits avec un SAN wildcard (validité 90 jours).

Annexe : Référence CLI de configuration

Le binaire setup s'exécute à l'intérieur du conteneur de passerelle via docker compose run --rm setup <subcommand> (Compose) ou en tant que hook Helm et CronJob (Kubernetes).

setup init — crée un tunnel via l'API Tunnels, génère une CA et un certificat serveur, enregistre la CA et écrit tous les résultats.

Drapeau

Description

Par défaut

--api-url

URL de base de l'API Anthropic. Également lu à partir de API_URL.

requis

--api-token

Jeton API avec portée tunnel. Également lu à partir de API_TOKEN.

requis

--output

Destination de sortie : dir:/path ou k8s-secret:NAME

k8s-secret:mcp-gateway

--cert-duration

Période de validité du certificat serveur

2160h (90 jours)

--token-version

Chaîne de détection de changement ; une nouvelle valeur déclenche la rotation du jeton tunnel

aucun

setup renew-cert — émet un nouveau certificat serveur signé par la CA stockée. Aucun appel API requis.

Drapeau

Description

Par défaut

--output

Destination de sortie : dir:/path ou k8s-secret:NAME

k8s-secret:mcp-gateway

--cert-duration

Période de validité du nouveau certificat

2160h (90 jours)

--renew-before

Ignorer si le certificat existant a plus de temps avant expiration

0 (toujours renouveler)

Définir --renew-before=720h rend la commande sans effet quand plus de 30 jours restent, adapté pour une exécution planifiée.

Articles connexes
Avez-vous trouvé la réponse à votre question ?