Déployer des tunnels MCP avec Docker Compose

Ce guide déploie la pile de tunnels sous forme de conteneurs renforcés sur un seul hôte. La même configuration peut être répliquée sur plusieurs hôtes pour assurer la disponibilité.

Avant de commencer

Vous avez besoin de :

• Un tunnel créé dans la Console. Suivez Créer un tunnel et notez l'ID du tunnel (tnl_...).
• Un moyen pour l'hôte de s'authentifier auprès de l'API Tunnels.
  • Accès programmatique (recommandé). Activez Set up programmatic access lors de la création du tunnel afin que le composant de configuration puisse s'authentifier via Workload Identity Federation. Notez l'ID de la règle de fédération (fdrl_...) et l'ID de votre organisation.
  • Manuel. Ignorez l'accès programmatique. Vous devrez obtenir le jeton du tunnel depuis la Console, générer vous-même une autorité de certification (CA) et un certificat serveur, puis enregistrer la CA dans la Console.
• Un hôte avec Docker et Docker Compose installés. Le flux manuel nécessite également openssl (version 1.1.1 ou ultérieure).
• Une connectivité réseau sortante depuis l'hôte vers api.anthropic.com (443 TCP) et le tunnel edge (7844 TCP et UDP). Consultez l'ensemble des exigences réseau.
• Un ou plusieurs serveurs MCP en cours d'exécution et accessibles depuis l'hôte aux adresses que vous configurerez sous routes. Si vous n'en avez pas encore, utilisez le serveur d'exemple.

Facultatif : utiliser un serveur MCP d'exemple

Si vous n'avez pas de serveur MCP disponible pour les tests, utilisez ce serveur minimal :

mkdir -p mcp-tunnel
cat > mcp-tunnel/hello_server.py <<'EOF'
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")
EOF

Les étapes d'installation suivantes effectuent un cd dans mcp-tunnel/ et indiquent où ajouter le service et la route correspondants.

Installation

Ce guide propose une approche de référence utilisant Docker Compose. Il vous incombe de l'adapter pour répondre aux exigences de sécurité de votre organisation.

Le fichier compose lit TUNNEL_TOKEN depuis l'environnement de l'hôte sans valeur par défaut, donc l'export doit être répété dans chaque nouveau shell et après un redémarrage.

Pour un déploiement multi-VM, copiez le répertoire mcp-tunnel/ sur chaque hôte, définissez TUNNEL_TOKEN et exécutez docker compose up -d. Dans le flux programmatique, TUNNEL_TOKEN est $(sudo cat data/tunnel-token) ; dans le flux manuel, c'est la valeur que vous avez copiée depuis la Console. Le même jeton de tunnel et les mêmes certificats fonctionnent sur toutes les répliques.

Vérifier le déploiement

Vérifiez de bout en bout en appelant un serveur MCP en amont depuis le côté Anthropic : consultez Utiliser les serveurs MCP tunnelisés. Avec le serveur MCP d'exemple, l'URL routée est https://echo.<your-tunnel-domain>/mcp. Si la vérification échoue, consultez Dépannage.

Mises à niveau

Exécutez les commandes de cette section depuis l'intérieur du répertoire de déploiement mcp-tunnel/.

Effectuer la rotation du jeton de tunnel

Avec l'accès programmatique, incrémentez --token-version dans la commande du service setup, définissez les identifiants Workload Identity Federation, générez un nouveau JWT OIDC et réexécutez le composant de configuration :

# Modifiez docker-compose.yaml : incrémentez l'entier dans l'argument
# --token-version du service setup (par exemple, --token-version=1 devient
# --token-version=2). Le binaire setup refuse d'effectuer la rotation si la
# valeur n'a pas changé.

export TUNNEL_ID=tnl_...
export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...
export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
# export ANTHROPIC_WORKSPACE_ID=wrkspc_...   # si votre règle est limitée à un espace de travail
# Régénérez ANTHROPIC_IDENTITY_TOKEN selon le guide du fournisseur WIF pour votre
# environnement (il aura expiré depuis l'installation).
export ANTHROPIC_IDENTITY_TOKEN=...

docker compose run --rm setup

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

L'argument --token-version est modifié dans docker-compose.yaml plutôt que passé en ligne de commande afin que la nouvelle valeur persiste pour les exécutions futures du composant de configuration. Le composant de configuration s'authentifie avec Workload Identity Federation ; il n'y a aucun jeton d'API à révoquer.

Sans accès programmatique, cliquez sur Rotate token sur la page de détails du tunnel dans la Console, puis mettez à jour la variable d'environnement TUNNEL_TOKEN sur chaque hôte et redémarrez cloudflared (docker compose up -d cloudflared).

Renouvellement du certificat

Il vous incombe de surveiller l'expiration et de renouveler le certificat serveur avant qu'il n'expire.

Avec l'accès programmatique :

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

Les arguments CLI remplacent la command du service setup (les arguments init) mais conservent son entrypoint, donc cela exécute /setup renew-cert --output=dir:/data.

Sans accès programmatique, signez un nouveau certificat serveur avec votre CA existante (la CA enregistrée dans la Console ne change pas) et remplacez data/tls.crt. Définissez d'abord TUNNEL_DOMAIN si vous exécutez ceci depuis un nouveau shell.

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

Dans les deux flux, le proxy interroge tls.cert_file et le recharge automatiquement, donc aucun redémarrage n'est nécessaire.

Étapes suivantes