Démarrage rapide des tunnels MCP

Connectez Claude à un serveur MCP privé à l'aide d'un déploiement Docker Compose local.

Ce guide de démarrage rapide vous emmène de zéro jusqu'à ce que Claude appelle un serveur MCP privé via un tunnel. Il utilise Docker Compose avec un provisionnement manuel des identifiants, ce qui constitue le chemin le plus court pour des tests en local. Pour les déploiements en production, consultez Déployer avec Helm ou Déployer avec Docker Compose.

Ce que vous allez construire

Une « tunnel stack » (pile de tunnel) à deux conteneurs (pile de tunnel composée du proxy et de cloudflared) ainsi qu'un serveur MCP d'exemple s'exécutant à ses côtés. Lorsque tout est en cours d'exécution, le serveur d'exemple est accessible depuis Claude à l'adresse https://echo.<your-tunnel-domain>/mcp, même si rien n'écoute sur un port public.

Ce dont vous avez besoin

Docker et Docker Compose sur une machine disposant d'un accès internet sortant.
Un rôle dans la Claude Console permettant de gérer les tunnels MCP. Consultez les prérequis du guide de la Console.
OpenSSL 1.1.1 ou version ultérieure. Préinstallé sur macOS et la plupart des distributions Linux ; sous Windows, installez-le séparément (le binaire openssl doit se trouver dans votre PATH).

1
Créer un tunnel
Dans la barre latérale de la Claude Console, accédez à Manage > MCP tunnels et cliquez sur New tunnel. Donnez-lui un nom. Laissez Set up programmatic access désactivé ; ce guide de démarrage rapide utilise le provisionnement manuel des identifiants.
Une fois le tunnel créé, ouvrez-le. Copiez deux valeurs depuis la section Connection :
- Domain (ressemble à abcd1234.tunnel.anthropic.com)
- Token (cliquez sur l'icône en forme d'œil, puis copiez)

Configurer le répertoire de déploiement

mkdir -p mcp-tunnel/{config,data}
cd mcp-tunnel
export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE   # from step 1
export TUNNEL_TOKEN='eyJ...'            # from step 1

Générer une CA et un certificat serveur

Le proxy termine le TLS interne (« inner TLS ») à l'aide d'un certificat signé par une autorité de certification (CA) que vous contrôlez. Générez les deux :

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"

cat > data/tls.ext <<EOF
subjectAltName = DNS:${TUNNEL_DOMAIN},DNS:*.${TUNNEL_DOMAIN}
authorityKeyIdentifier = keyid,issuer
extendedKeyUsage = serverAuth
EOF

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

chmod 644 data/tls.key

De retour dans la Console, sur la page de détail du tunnel, cliquez sur Add certificate et téléversez data/ca.crt (ou collez son contenu). Le statut du tunnel passe à Active.

Écrire le serveur MCP d'exemple

cat > 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

Écrire la configuration du proxy et le fichier compose

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

cat > docker-compose.yaml <<'EOF'
services:
  mcp-proxy:
    image: us-docker.pkg.dev/anthropic-public-registry/images/mcp-proxy@sha256:efb27b299d627e4134815663cb8896641eeaee025d734c0f695582b4df38f013
    volumes:
      - ./config/mcp-proxy.yaml:/etc/mcp-gateway/config.yaml:ro
      - ./data:/data:ro
    restart: unless-stopped

  cloudflared:
    image: cloudflare/cloudflared@sha256:6b599ca3e974349ead3286d178da61d291961182ec3fe9c505e1dd02c8ac31b0
    command: tunnel --no-autoupdate run --url http://localhost:8080
    environment:
      - TUNNEL_TOKEN
    network_mode: "service:mcp-proxy"
    restart: unless-stopped

  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
Le démarrer
docker compose up -d docker compose logs mcp-proxy | grep "route configured" docker compose logs cloudflared | grep "Registered tunnel connection"
Vous devriez voir une ligne route configured pour echo et quatre lignes Registered tunnel connection. Les conteneurs mettent quelques secondes à démarrer ; relancez les commandes de journaux si elles ne renvoient rien.
L'appeler depuis Claude
Dans la Console, accédez à Managed Agents > Sessions et créez une session. Dans le sélecteur d'agent, choisissez Create new agent, donnez un nom à l'agent et conservez le modèle prérempli. Cliquez sur + MCP Server, sélectionnez votre tunnel, définissez Subdomain sur echo et Path sur mcp. Puis demandez :

Use the hello tool to greet tunnel.

Vous devriez voir un appel d'outil suivi de son résultat.

Étapes suivantes

Le tunnel est vérifié de bout en bout. Pour y substituer votre propre serveur MCP, ajoutez-le à docker-compose.yaml (ou exécutez-le sur le même réseau Docker), ajoutez une route pour celui-ci dans config/mcp-proxy.yaml, puis redémarrez le proxy (docker compose restart mcp-proxy).

Pour les déploiements en production :

Déployer avec Docker Compose

Déploiement renforcé sur un hôte unique, avec ou sans accès programmatique.

Déployer avec Helm

Déploiement Kubernetes avec gestion automatique des identifiants.

Ce que vous allez construire

Ce dont vous avez besoin

Créer un tunnel