MCP-Server in Cloud Run hosten

In dieser Anleitung wird beschrieben, wie Sie einen Model Context Protocol-Server (MCP) mit streamfähigem HTTP-Transport in Cloud Run hosten und wie Sie MCP-Clients authentifizieren. Wenn Sie MCP noch nicht kennen, finden Sie im Einführungsleitfaden weitere Informationen.

MCP ist ein offenes Protokoll, das die Interaktion von KI-Agents mit ihrer Umgebung standardisiert. Der KI-Agent hostet einen MCP-Client und die Tools und Ressourcen, mit denen er interagiert, sind MCP-Server. Der MCP-Client kann über zwei verschiedene Transporttypen mit dem MCP-Server kommunizieren:

Sie können MCP-Clients und ‑Server auf demselben lokalen Computer hosten, einen MCP-Client lokal hosten und ihn mit Remote-MCP-Servern kommunizieren lassen, die auf einer Cloud-Plattform wie Cloud Run gehostet werden, oder sowohl den MCP-Client als auch den ‑Server auf einer Cloud-Plattform hosten.

Cloud Run unterstützt das Hosten von MCP-Servern mit streamable HTTP-Transport, aber nicht MCP-Server mit stdio-Transport.

Die Anleitung auf dieser Seite gilt, wenn Sie einen eigenen MCP-Server entwickeln oder einen vorhandenen MCP-Server verwenden.

Hinweise

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Make sure that billing is enabled for your Google Cloud project.

  6. Richten Sie Ihre Cloud Run-Entwicklungsumgebung in Ihrem Google Cloud -Projekt ein.
  7. Prüfen Sie, ob Sie die entsprechenden Berechtigungen zum Bereitstellen von Diensten haben und ob Ihrem Konto die Rollen Cloud Run-Administrator (roles/run.admin) und Dienstkontonutzer (roles/iam.serviceAccountUser) zugewiesen sind.

    8. Rollen zuweisen

    Console

    1. Rufen Sie in der Google Cloud Console die Seite IAM auf.

      IAM aufrufen
    2. Wählen Sie das Projekt aus.
    3. Klicken Sie auf Zugriff erlauben.

    4. Geben Sie im Feld Neue Hauptkonten Ihre Nutzer-ID ein. Dies ist in der Regel die E-Mail-Adresse des Google-Kontos, das zum Bereitstellen des Cloud Run-Dienstes verwendet wird.

    5. Wählen Sie in der Liste Rolle auswählen eine Rolle aus.
    6. Wenn Sie weitere Rollen zuweisen möchten, klicken Sie auf Weitere Rolle hinzufügen und fügen Sie weitere Rollen hinzu.
    7. Klicken Sie auf Speichern.

    gcloud

    So weisen Sie Ihrem Konto die erforderlichen IAM-Rollen für Ihr Projekt zu:

       gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=PRINCIPAL \
       --role=ROLE

    Ersetzen Sie:

    • PROJECT_NUMBER durch Ihre Google Cloud Projektnummer.
    • PROJECT_ID durch Ihre Google Cloud Projekt-ID.
    • PRINCIPAL durch das Konto, für das Sie die Bindung hinzufügen. Dies ist in der Regel die E-Mail-Adresse des Google-Kontos, mit dem der Cloud Run-Dienst bereitgestellt wird.
    • ROLE durch die Rolle, die Sie dem Bereitstellerkonto hinzufügen.

    Remote-SSE- oder streamfähige HTTP-MCP-Server hosten

    MCP-Server, die Server-Sent Events (SSE) oder den streamfähigen HTTP-Transport verwenden, können remote von ihren MCP-Clients gehostet werden.

    Wenn Sie diesen Typ von MCP-Server in Cloud Run bereitstellen möchten, können Sie den MCP-Server als Container-Image oder als Quellcode (in der Regel Node.js oder Python) bereitstellen, je nachdem, wie der MCP-Server verpackt ist.

    Container-Images

    Remote-MCP-Server, die als Container-Images verteilt werden, sind Webserver, die an einem bestimmten Port auf HTTP-Anfragen warten. Das bedeutet, dass sie dem Container-Laufzeitvertrag von Cloud Run entsprechen und in einem Cloud Run-Dienst bereitgestellt werden können.

    Wenn Sie einen als Container-Image verpackten MCP-Server bereitstellen möchten, benötigen Sie die URL des Container-Images und den Port, über den Anfragen empfangen werden sollen. Diese können mit dem folgenden gcloud CLI-Befehl bereitgestellt werden:

    gcloud run deploy --image IMAGE_URL --port PORT

    Ersetzen Sie:

    • IMAGE_URL durch die Container-Image-URL, z. B. us-docker.pkg.dev/cloudrun/container/mcp.
    • Ersetzen Sie PORT durch den Port, den er überwacht, z. B. 3000.

    Quellen

    Remote-MCP-Server, die nicht als Container-Images bereitgestellt werden, können aus ihren Quellen in Cloud Run bereitgestellt werden, insbesondere wenn sie in Node.js oder Python geschrieben sind.

    1. Klonen Sie das Git-Repository des MCP-Servers: 

      git clone https://github.com/ORGANIZATION/REPOSITORY.git

    2. Rufen Sie das Stammverzeichnis des MCP-Servers auf: 

      cd REPOSITORY

    3. Stellen Sie die Anwendung mit dem folgenden gcloud CLI-Befehl in Cloud Run bereit: 

      gcloud run deploy --source .

    Nachdem Sie Ihren HTTP-MCP-Server in Cloud Run bereitgestellt haben, erhält er eine HTTPS-URL. Die Kommunikation kann den integrierten Support von Cloud Run für das Streamen von HTTP-Antworten nutzen.

    MCP-Clients authentifizieren

    Je nachdem, wo Sie den MCP-Client gehostet haben, finden Sie hier den für Sie relevanten Abschnitt:

Lokale MCP-Clients authentifizieren

Wenn der KI-Agent, auf dem der MCP-Client gehostet wird, auf einem lokalen Computer ausgeführt wird, verwenden Sie eine der folgenden Methoden, um den MCP-Client zu authentifizieren:

Weitere Informationen finden Sie in der MCP-Spezifikation zur Authentifizierung.

IAM-Invoker-Berechtigung

Standardmäßig müssen alle Anfragen an die URL von Cloud Run-Diensten mit der IAM-Rolle Cloud Run Invoker (roles/run.invoker) autorisiert werden. Diese IAM-Richtlinienbindung sorgt dafür, dass ein starker Sicherheitsmechanismus zur Authentifizierung Ihres lokalen MCP-Clients verwendet wird.

Nachdem Sie Ihren MCP-Server in einem Cloud Run-Dienst in einer Region bereitgestellt haben, führen Sie den Cloud Run-Proxy auf Ihrem lokalen Computer aus, um den Remote-MCP-Server mit Ihren eigenen Anmeldedaten sicher für Ihren Client verfügbar zu machen:

gcloud run services proxy MCP_SERVER_NAME --region REGION --port=3000

Ersetzen Sie:

  • MCP_SERVER_NAME durch den Namen Ihres Cloud Run-Dienstes
  • REGION durch die Google Cloud Region, in der Sie Ihren Dienst bereitgestellt haben. Beispiel: europe-west1.

Mit dem Cloud Run-Proxybefehl wird ein lokaler Proxy auf Port 3000 erstellt, der Anfragen an den Remote-MCP-Server weiterleitet und Ihre Identität einfügt.

Aktualisieren Sie die MCP-Konfigurationsdatei Ihres MCP-Clients mit Folgendem:

{
  "mcpServers": {
    "cloud-run": {
      "url": "http://localhost:3000/sse"
    }
  }
}

Wenn Ihr MCP-Client das Attribut url nicht unterstützt, verwenden Sie das mcp-remote-npm-Paket:

{
  "mcpServers": {
    "cloud-run": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:3000/sse"
      ]
    }
  }
}

OIDC-ID-Token

Je nachdem, ob der MCP-Client Header bereitstellt oder eine Möglichkeit zur Bereitstellung eines benutzerdefinierten authentifizierten Transports verwendet, können Sie den MCP-Client mit einem OIDC-ID-Token authentifizieren.

Sie können verschiedene Google-Authentifizierungsbibliotheken verwenden, um ein ID-Token aus der Laufzeitumgebung abzurufen, z. B. die Google-Authentifizierungsbibliothek für Python. Dieses Token muss die richtige Zielgruppenanforderung enthalten, die der *.run.app-URL des empfangenden Dienstes entspricht, es sei denn, Sie verwenden benutzerdefinierte Zielgruppen. Sie müssen das ID-Token auch in Clientanfragen wie Authorization: Bearer <token value> einfügen.

Wenn der MCP-Client weder Header noch Transport verfügbar macht, verwenden Sie eine andere Authentifizierungsmethode.

MCP-Clients authentifizieren, die in Cloud Run ausgeführt werden

Wenn der KI-Agent, auf dem der MCP-Client gehostet wird, in Cloud Run ausgeführt wird, verwenden Sie eine der folgenden Methoden, um den MCP-Client zu authentifizieren:

MCP-Server als Sidecar bereitstellen

Der MCP-Server kann als Sidecar bereitgestellt werden, in dem der MCP-Client ausgeführt wird.

Für diesen Anwendungsfall ist keine spezielle Authentifizierung erforderlich, da sich der MCP-Client und der MCP-Server auf derselben Instanz befinden. Der Client kann über einen Port auf http://localhost:PORT eine Verbindung zum MCP-Server herstellen. Ersetzen Sie PORT durch einen anderen Port als den, der zum Senden von Anfragen an den Cloud Run-Dienst verwendet wird.

Dienst-zu-Dienst authentifizieren

Wenn der MCP-Server und der MCP-Client als separate Cloud Run-Dienste ausgeführt werden, lesen Sie den Abschnitt Dienst-zu-Dienst-Authentifizierung.

Cloud Service Mesh verwenden

Ein Agent, auf dem ein MCP-Client gehostet wird, kann über Cloud Service Mesh eine Verbindung zu einem Remote-MCP-Server herstellen.

Sie können den MCP-Serverdienst so konfigurieren, dass er einen Kurznamen im Mesh hat, und der MCP-Client kann über den Kurznamen http://mcp-server mit dem MCP-Server kommunizieren. Die Authentifizierung wird vom Mesh verwaltet.

Nächste Schritte