MCP-Server in Cloud Run hosten

In dieser Anleitung wird beschrieben, wie Sie einen MCP-Server (Model Context Protocol) mit streamfähigem HTTP-Transport in Cloud Run hosten. Außerdem finden Sie hier Informationen zur Authentifizierung von MCP-Clients. Wenn Sie noch nicht mit MCP vertraut sind, lesen Sie die folgenden Ressourcen:

MCP ist ein offenes Protokoll, das die Interaktion von KI-Agenten 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 MCP-Server auf einer Cloud-Plattform hosten.

Cloud Run unterstützt das Hosten von MCP-Servern mit streamfähigem HTTP-Transport, aber nicht von MCP-Servern mit Stdio-Transport.

Das folgende Diagramm zeigt, wie der MCP-Client die Absicht des KI-Agenten aufnimmt und eine standardisierte Anfrage an MCP-Server sendet, in der das auszuführende Tool angegeben wird. Nachdem der MCP-Server die Aktion ausgeführt und die Ergebnisse abgerufen hat, gibt er das Ergebnis in einem einheitlichen Format an den MCP-Client zurück.

Ein MCP-Server interagiert über einen MCP-Client mit einem KI-Agenten.
Abbildung 1.Der in Cloud Run gehostete MCP-Server interagiert mit dem MCP-Client, der mit dem KI-Agenten interagiert.

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

Hinweis

  1. Melden Sie sich in Ihrem Google Cloud -Konto an. Wenn Sie noch kein Google Cloud-Konto haben, erstellen Sie ein Konto, um zu testen, wie sich unsere Produkte in realen Szenarien schlagen. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify 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.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Richten Sie Ihre Cloud Run-Entwicklungsumgebung ein in Ihrem Google Cloud Projekt.
  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 „“ Zugriffsrechte erteilen.

    4. Geben Sie im Feld Neue Hauptkonten Ihre Nutzer-ID ein. In der Regel ist das die E-Mail-Adresse, die 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 jede zusätzliche Rolle 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 Projekt nummer.
    • PROJECT_ID durch Ihre Google Cloud Projekt-ID.
    • PRINCIPAL durch das Konto, für das Sie die Bindung hinzufügen. In der Regel ist das die E-Mail-Adresse, die zum Bereitstellen des Cloud Run-Dienstes verwendet wird.
    • ROLE durch die Rolle, die Sie dem Konto des Bereitstellers hinzufügen.

Remote-MCP-Server mit SSE oder streamfähigem HTTP hosten

MCP-Server, die Server-Sent Events (SSE) oder streamfähiges HTTP 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 je nach Paketierung als Container-Image oder als Quellcode (in der Regel Node.js oder Python) bereitstellen.

Container-Images

Remote-MCP-Server, die als Container-Images verteilt werden, sind Webserver, die auf 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, auf dem er Anfragen empfängt. 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.
  • PORT durch den Port, auf dem er wartet, 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. Wechseln Sie zum Stammverzeichnis des MCP-Servers: 

    cd REPOSITORY

  3. Stellen Sie den Server 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 der MCP Server eine HTTPS-URL und die Kommunikation kann die integrierte Unterstützung von Cloud Run für das Streaming von HTTP Antworten nutzen.

MCP-Clients für KI-Agenten authentifizieren

Je nachdem, wo Sie den MCP-Client gehostet haben, lesen Sie den entsprechenden Abschnitt:

Lokale MCP-Clients authentifizieren

Wenn der KI-Agent, der den MCP-Client hostet, 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 unter Authentifizierung.

IAM-Invoker-Berechtigung

Standardmäßig erfordert die URL von Cloud Run-Diensten, dass alle Anfragen mit der IAM-Rolle „Cloud Run Invoker“ (roles/run.invoker) autorisiert werden. Diese IAM-Richtlinienbindung sorgt dafür, dass ein starker Sicherheitsmechanismus verwendet wird, um Ihren lokalen MCP-Client zu authentifizieren.

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.

Der Cloud Run-Proxy-Befehl erstellt einen lokalen Proxy auf Port 3000, 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 url Attribut 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 den richtigen Zielgruppenanspruch haben, der mit der URL des empfangenden Dienstes übereinstimmt, es sei denn, Sie verwenden benutzerdefinierte Zielgruppen.*.run.app Sie müssen das ID-Token auch in Clientanfragen angeben, z. B. Authorization: Bearer <token value>.

Wenn der MCP-Client weder Header noch Transport bereitstellt, verwenden Sie eine andere Authentifizierungsmethode.

In Cloud Run ausgeführte MCP-Clients authentifizieren

Wenn der KI-Agent, der den MCP-Client hostet, 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 MCP-Client und 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-Authentifizierung

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

Cloud Service Mesh verwenden

Ein Agent, der einen MCP-Client hostet, kann mit Cloud Service Mesh eine Verbindung zu einem Remote-MCP-Server herstellen. Mit einem Service Mesh wird die Orchestrierung von Mikrodiensten vereinfacht, da Authentifizierung und Traffic-Management automatisch erfolgen.

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

Nächste Schritte