Déployer des tunnels MCP avec Docker Compose

Ce parcours nécessite que l'hôte dispose d'un fournisseur d'identité OIDC (tel qu'un serveur de métadonnées de VM cloud ou SPIFFE). Si ce n'est pas le cas, utilisez plutôt l'onglet Sans accès programmatique.

Le composant de configuration utilise la Workload Identity Federation pour récupérer le jeton du tunnel, générer une CA et un certificat serveur, et enregistrer la CA auprès d'Anthropic.

1. 1

   Préparer le répertoire de déploiement

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

   

   Les conteneurs s'exécutent avec l'UID non root 65532 et ont besoin d'un accès en écriture à data/.

2. 2

   Écrire docker-compose.yaml

   Le fichier compose épingle les images par empreinte SHA-256, exécute chaque conteneur en tant que non root avec un système de fichiers en lecture seule, supprime toutes les capacités Linux et désactive l'élévation de privilèges.

   cat > docker-compose.yaml <<'EOF'
   services:
     setup:
       image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:d243d30642d39857a0579e465cb3b9bf3ae7c1141e83143bb6856777a31467a5
       entrypoint: ["/setup"]
       command:
         - init
         - --api-url=https://api.anthropic.com
         - --output=dir:/data
         - --token-version=1
       environment:
         - TUNNEL_ID
         - ANTHROPIC_FEDERATION_RULE_ID
         - ANTHROPIC_ORGANIZATION_ID
         - ANTHROPIC_WORKSPACE_ID
         - ANTHROPIC_IDENTITY_TOKEN
       volumes:
         - ./data:/data
       user: "65532:65532"
       read_only: true
       security_opt:
         - no-new-privileges:true
       cap_drop:
         - ALL
       profiles: ["setup"]
   
     cloudflared:
       image: cloudflare/cloudflared@sha256:0e56c13c7058fcef9c4f0e7d83372f82330548dbf8f8b366f3d8b506526d93b2
       command: tunnel --no-autoupdate run --url http://localhost:8080
       environment:
         - TUNNEL_TOKEN
       # Partager le netns du proxy pour que localhost:8080 l'atteigne.
       network_mode: "service:mcp-proxy"
       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-proxy:
       image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:d243d30642d39857a0579e465cb3b9bf3ae7c1141e83143bb6856777a31467a5
       volumes:
         - ./config/mcp-proxy.yaml:/etc/mcp-gateway/config.yaml:ro
         - ./data:/data: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"
   EOF

   

   Si vous utilisez le serveur MCP d'exemple, ajoutez-le en tant que service :

   cat >> docker-compose.yaml <<'EOF'
   
     hello-mcp:
       image: python:3.13-slim
       working_dir: /app
       volumes:
         - ./hello_server.py:/app/hello_server.py:ro
       command: sh -c "pip install --quiet mcp && python hello_server.py"
       restart: unless-stopped
   EOF

   
3. 3

   Provisionner le tunnel

   Définissez les identifiants. Laissez TUNNEL_ID non défini pour que le composant de configuration crée un tunnel ; définissez-le pour vous rattacher à un tunnel existant depuis la Console :

   # export TUNNEL_ID=tnl_...   # à définir pour se rattacher à un tunnel existant
   export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...
   export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000

   

   Si votre règle de fédération est limitée à un espace de travail autre que l'espace de travail par défaut de votre organisation, définissez également ANTHROPIC_WORKSPACE_ID=wrkspc_... ; sinon, le composant de configuration utilise l'espace de travail par défaut. Un tunnel créé automatiquement est créé dans cet espace de travail.

   Définissez ANTHROPIC_IDENTITY_TOKEN sur un JWT OIDC provenant du fournisseur d'identité de cet hôte. Suivez le guide WIF pour votre fournisseur pour enregistrer l'émetteur, définir le sujet de la règle et émettre le jeton ; l'audience de la règle doit correspondre à l'audience que vous demandez lors de l'émission.

   Exécutez le composant de configuration :

   docker compose run --rm setup

   

   setup init est idempotent vis-à-vis de data/ : le réexécuter réutilise l'ID du tunnel et la CA déjà stockés à cet endroit et ne crée jamais de second tunnel. Une nouvelle CA n'est générée et enregistrée que lorsque data/ est vide ou que TUNNEL_ID a changé ; dans ce cas, la limite de deux certificats actifs s'applique, donc révoquez-en un dans la Console au préalable si les deux emplacements sont occupés.

   Consultez Échecs d'authentification du composant de configuration en cas d'erreur.

   Récupérez le domaine de votre tunnel et exportez-le pour les étapes suivantes :

   export TUNNEL_DOMAIN=$(sudo cat data/tunnel-domain)
   echo "$TUNNEL_DOMAIN"

   
4. 4

   Écrire la configuration du proxy

   tunnel_domain est obligatoire : le proxy l'utilise pour retirer le suffixe de domaine des noms d'hôte entrants avant de rechercher le sous-domaine dans routes. routes est une table de correspondance plate entre sous-domaine et URL en amont, et non une liste.

   cat > config/mcp-proxy.yaml <<EOF
   listen_addr: ":8080"
   log_level: info
   shutdown_timeout: 30s
   tunnel_domain: ${TUNNEL_DOMAIN}
   tls:
     cert_file: /data/tls.crt
     key_file: /data/tls.key
   routes:
     echo: http://hello-mcp:9000
   EOF

   

   La route echo: cible le serveur MCP d'exemple ; remplacez-la par vos propres routes (ou ajoutez-les). Consultez la référence de configuration du proxy pour tous les champs disponibles.

5. 5

   Démarrer le déploiement

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

   

Utilisez ce flux si vous n'avez pas activé Set up programmatic access, ou pour le développement local et les tests. Il n'y a pas de service setup.

1. 1

   Obtenir le jeton et le domaine du tunnel depuis la Console

   Sur la page de détail du tunnel, copiez le Domain (il a la forme abcd1234.tunnel.anthropic.com), puis cliquez sur l'icône en forme d'œil à côté de Token pour récupérer le jeton du tunnel et utilisez l'icône de copie pour le copier.

   Définissez les deux comme variables shell pour le reste du guide :

   export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE
   export TUNNEL_TOKEN='eyJ...'

   
2. 2

   Créer la structure et générer les certificats

   mkdir -p mcp-tunnel/{data,config}
   cd mcp-tunnel

   

   Le proxy écoute sur :8080 en WebSocket simple ; la poignée de main TLS interne a lieu à l'intérieur de ce flux WebSocket à l'aide de ces certificats. Anthropic vérifie la poignée de main interne par rapport à la CA que vous enregistrez dans la Console. Le Subject Alternative Name (SAN) du certificat serveur doit inclure *.<tunnel-domain> comme décrit dans les exigences relatives aux certificats.

   # CA auto-signée. Extensions explicites pour satisfaire les exigences
   # du certificat quels que soient les paramètres par défaut de 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) garantit le fonctionnement sur
   # 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
   
   # Permet au conteneur proxy non root (UID 65532) de lire la clé depuis
   # le montage bind. Sans le bit de lecture pour tous, le conteneur ne peut pas ouvrir
   # un fichier appartenant à l'hôte.
   chmod 644 data/tls.key

   
3. 3

   Enregistrer le certificat CA dans la Console

   Sur la page de détails du tunnel, faites défiler jusqu'à la section Certificates et cliquez sur Add certificate. Téléversez data/ca.crt directement avec Choose file (la fenêtre modale accepte .pem, .crt et .cer), ou collez son contenu :

   cat data/ca.crt

   

   Le badge Needs certificate à côté du nom du tunnel disparaît une fois qu'un certificat est enregistré. Consultez Ajouter un certificat CA.

4. 4

   Écrire la configuration du proxy

   tunnel_domain est obligatoire : le proxy l'utilise pour retirer le suffixe de domaine des noms d'hôte entrants avant de rechercher le sous-domaine dans routes. routes est une table de correspondance plate entre sous-domaine et URL en amont, et non une liste.

   cat > config/mcp-proxy.yaml <<EOF
   listen_addr: ":8080"
   log_level: info
   tunnel_domain: ${TUNNEL_DOMAIN}
   tls:
     cert_file: /data/tls.crt
     key_file: /data/tls.key
   routes:
     echo: http://hello-mcp:9000
   EOF

   

   La route echo: cible le serveur MCP d'exemple ; remplacez-la par vos propres routes (ou ajoutez-les). Consultez la référence de configuration du proxy pour tous les champs disponibles.

5. 5

   Écrire docker-compose.yaml

   Le paramètre network_mode: "service:mcp-proxy" place cloudflared dans l'espace de noms réseau du proxy afin que localhost:8080 à l'intérieur du conteneur cloudflared atteigne le proxy. L'option --url http://localhost:8080 fournit à cloudflared sa cible de transfert ; sans cette option, cloudflared n'a aucune route pour les requêtes entrantes et renvoie une erreur 503.

   cat > docker-compose.yaml <<'EOF'
   services:
     cloudflared:
       image: cloudflare/cloudflared@sha256:0e56c13c7058fcef9c4f0e7d83372f82330548dbf8f8b366f3d8b506526d93b2
       # --url est requis : aucune règle d'ingress n'est poussée dans le flux manuel,
       # donc sans lui, cloudflared renvoie une 503 à chaque requête.
       command: tunnel --no-autoupdate run --url http://localhost:8080
       environment:
         - TUNNEL_TOKEN
       # Partagez le netns du proxy pour que localhost:8080 l'atteigne.
       network_mode: "service:mcp-proxy"
       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-proxy:
       image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:d243d30642d39857a0579e465cb3b9bf3ae7c1141e83143bb6856777a31467a5
       volumes:
         - ./config/mcp-proxy.yaml:/etc/mcp-gateway/config.yaml:ro
         - ./data:/data: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"
   EOF

   

   Si vous utilisez le serveur MCP d'exemple, ajoutez-le en tant que service :

   cat >> docker-compose.yaml <<'EOF'
   
     hello-mcp:
       image: python:3.13-slim
       working_dir: /app
       volumes:
         - ./hello_server.py:/app/hello_server.py:ro
       command: sh -c "pip install --quiet mcp && python hello_server.py"
       restart: unless-stopped
   EOF

   
6. 6

   Démarrer le déploiement

   docker compose up -d

   