MCP-Tunnel-Schnellstart

Verbinde Claude mit einem privaten MCP-Server über ein lokales Docker-Compose-Deployment.

Dieser Schnellstart führt dich von null bis zu dem Punkt, an dem Claude einen privaten MCP-Server über einen Tunnel aufruft. Er verwendet Docker Compose mit manueller Bereitstellung von Zugangsdaten („credential provisioning“), was der kürzeste Weg für lokale Tests ist. Für Produktions-Deployments siehe Mit Helm bereitstellen oder Mit Docker Compose bereitstellen.

Was du bauen wirst

Einen Tunnel-Stack aus zwei Containern (dem Proxy und cloudflared) sowie einen Beispiel-MCP-Server, der daneben läuft. Wenn alles läuft, ist der Beispielserver von Claude aus unter https://echo.<your-tunnel-domain>/mcp erreichbar, obwohl nichts an einem öffentlichen Port lauscht.

Was du brauchst

Docker und Docker Compose auf einem Rechner mit ausgehendem Internetzugang.
Eine Rolle in der Claude Console, die MCP-Tunnel verwalten kann. Siehe die Voraussetzungen im Console-Leitfaden.
OpenSSL 1.1.1 oder neuer. Auf macOS und den meisten Linux-Distributionen vorinstalliert; unter Windows musst du es separat installieren (die openssl-Binärdatei muss sich in deinem PATH befinden).

1
Einen Tunnel erstellen
Gehe in der Seitenleiste der Claude Console zu Manage > MCP tunnels und klicke auf New tunnel. Gib ihm einen Namen. Lass Set up programmatic access deaktiviert; dieser Schnellstart verwendet die manuelle Bereitstellung von Zugangsdaten.
Öffne den Tunnel, nachdem er erstellt wurde. Kopiere zwei Werte aus dem Abschnitt Connection:
- Domain (sieht aus wie abcd1234.tunnel.anthropic.com)
- Token (klicke auf das Augensymbol, dann kopieren)

Das Deployment-Verzeichnis einrichten

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

Eine CA und ein Serverzertifikat erzeugen

Der Proxy terminiert inneres TLS („inner TLS“) mit einem Zertifikat, das von einer CA signiert ist, die du kontrollierst. Erzeuge beides:

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

Zurück in der Console klickst du auf der Detailseite des Tunnels auf Add certificate und lädst data/ca.crt hoch (oder fügst den Inhalt ein). Der Tunnelstatus wechselt auf Active.

Den Beispiel-MCP-Server schreiben

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

Die Proxy-Konfiguration und die Compose-Datei schreiben

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
Starten
docker compose up -d docker compose logs mcp-proxy | grep "route configured" docker compose logs cloudflared | grep "Registered tunnel connection"
Du solltest eine Zeile route configured für echo und vier Zeilen Registered tunnel connection sehen. Die Container brauchen einige Sekunden zum Starten; führe die Log-Befehle erneut aus, falls sie leer zurückkommen.
Von Claude aus aufrufen
Gehe in der Console zu Managed Agents > Sessions und erstelle eine Session. Wähle in der Agent-Auswahl Create new agent, gib dem Agenten einen Namen und behalte das vorausgefüllte Modell bei. Klicke auf + MCP Server, wähle deinen Tunnel aus, setze Subdomain auf echo und Path auf mcp. Frage dann:

Use the hello tool to greet tunnel.

Du solltest einen Tool-Aufruf gefolgt von seinem Ergebnis sehen.

Nächste Schritte

Der Tunnel ist Ende-zu-Ende verifiziert. Um deinen eigenen MCP-Server einzusetzen, füge ihn zu docker-compose.yaml hinzu (oder betreibe ihn im selben Docker-Netzwerk), füge in config/mcp-proxy.yaml eine Route für ihn hinzu und starte dann den Proxy neu (docker compose restart mcp-proxy).

Für Produktions-Deployments:

Mit Docker Compose bereitstellen

Gehärtetes Single-Host-Deployment, mit oder ohne programmatischen Zugriff.

Mit Helm bereitstellen

Kubernetes-Deployment mit automatischer Verwaltung von Zugangsdaten.

Was du bauen wirst

Was du brauchst

Einen Tunnel erstellen