MCP-Tunnel mit Docker Compose bereitstellen

Diese Anleitung stellt den Tunnel-Stack als gehärtete Container auf einem einzelnen Host bereit. Dieselbe Konfiguration kann für höhere Verfügbarkeit auf mehrere Hosts repliziert werden.

Bevor du beginnst

Du benötigst:

• Einen in der Console erstellten Tunnel. Folge Tunnel erstellen und notiere die Tunnel-ID (tnl_...).
• Eine Möglichkeit für den Host, sich bei der Tunnels-API zu authentifizieren.
  • Programmatischer Zugriff (empfohlen). Aktiviere Set up programmatic access beim Erstellen des Tunnels, damit sich die Setup-Komponente über Workload Identity Federation authentifizieren kann. Notiere die Federation-Rule-ID (fdrl_...) und deine Organisations-ID.
  • Manuell. Überspringe den programmatischen Zugriff. Du wirst das Tunnel-Token aus der Console abrufen, selbst eine CA und ein Serverzertifikat generieren und die CA in der Console registrieren.
• Einen Host mit installiertem Docker und Docker Compose. Der manuelle Ablauf erfordert zusätzlich openssl (1.1.1 oder neuer).
• Ausgehende Netzwerkverbindung vom Host zu api.anthropic.com (443 TCP) und zur Tunnel-Edge (7844 TCP und UDP). Siehe die vollständigen Netzwerkanforderungen.
• Einen oder mehrere MCP-Server, die laufen und vom Host aus unter den Adressen erreichbar sind, die du unter routes konfigurieren wirst. Falls du noch keinen hast, verwende den Beispielserver.

Optional: Einen Beispiel-MCP-Server verwenden

Falls du keinen MCP-Server zum Testen zur Verfügung hast, verwende diesen minimalen Server:

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

Die folgenden Installationsschritte wechseln mit cd in mcp-tunnel/ und weisen darauf hin, wo der entsprechende Service und die Route hinzugefügt werden müssen.

Installation

Diese Anleitung bietet einen Referenzansatz mit Docker Compose. Du bist dafür verantwortlich, ihn an die Sicherheitsanforderungen deiner Organisation anzupassen.

Die Compose-Datei liest TUNNEL_TOKEN ohne Standardwert aus der Host-Umgebung, daher muss der Export in jeder neuen Shell und nach einem Neustart wiederholt werden.

Für ein Multi-VM-Deployment kopiere das Verzeichnis mcp-tunnel/ auf jeden Host, setze TUNNEL_TOKEN und führe docker compose up -d aus. Im programmatischen Ablauf ist TUNNEL_TOKEN gleich $(sudo cat data/tunnel-token); im manuellen Ablauf ist es der Wert, den du aus der Console kopiert hast. Dasselbe Tunnel-Token und dieselben Zertifikate funktionieren über alle Replikate hinweg.

Das Deployment verifizieren

Verifiziere Ende-zu-Ende, indem du einen Upstream-MCP-Server von Anthropics Seite aus aufrufst: siehe Die getunnelten MCP-Server verwenden. Mit dem Beispiel-MCP-Server lautet die geroutete URL https://echo.<your-tunnel-domain>/mcp. Falls die Verifizierung fehlschlägt, siehe Fehlerbehebung.

Upgrades

Führe die Befehle in diesem Abschnitt innerhalb des Deployment-Verzeichnisses mcp-tunnel/ aus.

Das Tunnel-Token rotieren

Mit programmatischem Zugriff: Erhöhe --token-version im Command des setup-Services, setze die Workload-Identity-Federation-Identifikatoren, erstelle ein frisches OIDC-JWT und führe die Setup-Komponente erneut aus:

# Bearbeite docker-compose.yaml: erhöhe die Ganzzahl im Argument
# --token-version des Setup-Services (z. B. --token-version=1 zu
# --token-version=2). Das Setup-Binary verweigert die Rotation, wenn der
# Wert unverändert ist.

export TUNNEL_ID=tnl_...
export ANTHROPIC_FEDERATION_RULE_ID=fdrl_...
export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000
# export ANTHROPIC_WORKSPACE_ID=wrkspc_...   # falls deine Regel Workspace-bezogen ist
# Erzeuge ANTHROPIC_IDENTITY_TOKEN neu gemäß der WIF-Provider-Anleitung für
# deine Umgebung (es ist seit der Installation abgelaufen).
export ANTHROPIC_IDENTITY_TOKEN=...

docker compose run --rm setup

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

Das Argument --token-version wird in docker-compose.yaml bearbeitet statt auf der Kommandozeile übergeben, damit der neue Wert für zukünftige Ausführungen der Setup-Komponente erhalten bleibt. Die Setup-Komponente authentifiziert sich über Workload Identity Federation; es gibt kein API-Token zu widerrufen.

Ohne programmatischen Zugriff: Klicke auf der Tunnel-Detailseite in der Console auf Rotate token, aktualisiere dann die Umgebungsvariable TUNNEL_TOKEN auf jedem Host und starte cloudflared neu (docker compose up -d cloudflared).

Zertifikatserneuerung

Du bist dafür verantwortlich, das Ablaufdatum zu überwachen und das Serverzertifikat zu erneuern, bevor es abläuft.

Mit programmatischem Zugriff:

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

Die CLI-Argumente ersetzen den command des setup-Services (die init-Argumente), behalten aber dessen entrypoint bei, sodass dies /setup renew-cert --output=dir:/data ausführt.

Ohne programmatischen Zugriff: Signiere ein neues Serverzertifikat mit deiner bestehenden CA (die in der Console registrierte CA ändert sich nicht) und ersetze data/tls.crt. Setze zuerst TUNNEL_DOMAIN, falls du dies in einer neuen Shell ausführst.

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

In beiden Abläufen überwacht der Proxy tls.cert_file und lädt es automatisch neu, sodass kein Neustart erforderlich ist.

Nächste Schritte