Démarrage rapide des tunnels MCP

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

Ce démarrage rapide vous guide 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 les tests locaux. Pour les déploiements en production, consultez Déployer avec Helm ou Déployer avec Docker Compose.

Ce que vous allez construire

Une pile de tunnel à deux conteneurs (le proxy et cloudflared) ainsi qu'un exemple de serveur MCP s'exécutant à ses côtés. Lorsque tout est en cours d'exécution, l'exemple de serveur 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).

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 l'option Set up programmatic access désactivée ; ce 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 à l'aide d'un certificat signé par une CA (autorité de certification) 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étails du tunnel, cliquez sur Add certificate et téléversez data/ca.crt (ou collez son contenu). Le statut du tunnel passe à Active.

Écrire l'exemple de serveur MCP

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

Démarrer le tout
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 journalisation 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 remplacer l'exemple par votre propre serveur MCP, ajoutez-le à docker-compose.yaml (ou exécutez-le sur le même réseau Docker), ajoutez une route correspondante 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 seul hôte, avec ou sans accès programmatique.

Déployer avec Helm

Déploiement Kubernetes avec gestion automatique des identifiants.

Was this page helpful?

Ce que vous allez construire

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

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 l'option Set up programmatic access désactivée ; ce 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 à l'aide d'un certificat signé par une CA (autorité de certification) 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étails du tunnel, cliquez sur Add certificate et téléversez data/ca.crt (ou collez son contenu). Le statut du tunnel passe à Active.

Écrire l'exemple de serveur MCP

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

Démarrer le tout
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 journalisation 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

Pour les déploiements en production :

Déployer avec Docker Compose

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

Déployer avec Helm

Déploiement Kubernetes avec gestion automatique des identifiants.

Was this page helpful?

Ce que vous allez construire

Ce dont vous avez besoin

Étapes suivantes

Ce que vous allez construire

Ce dont vous avez besoin

Étapes suivantes

Ce que vous allez construire

Ce dont vous avez besoin

Étapes suivantes

Ce que vous allez construire

Ce dont vous avez besoin

Étapes suivantes