MCP-Server in Cloud Run hosten

In diesem Leitfaden wird beschrieben, wie Sie einen MCP-Server (Model Context Protocol) mit streamfähigem HTTP-Transport in Cloud Run hosten. Außerdem finden Sie hier eine Anleitung zur Authentifizierung von MCP-Clients. Wenn Sie noch keine Erfahrung mit MCP haben, 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 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 übernimmt 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 auf Cloud Run gehostete MCP-Server interagiert mit dem MCP-Client, der wiederum mit dem KI-Agenten interagiert.

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

Hinweis

  1. Melden Sie sich in Ihrem Google Cloud -Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, erstellen Sie einfach ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. 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 in Ihrem Google Cloud -Projekt ein.
  7. Prüfen Sie, ob Sie die erforderlichen 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. Informationen zum Zuweisen der Rollen

    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. Dies ist in der Regel 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 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, die zum Bereitstellen des Cloud Run-Dienstes verwendet wird.
    • ROLE durch die Rolle, die Sie dem Deployer-Konto hinzufügen.
  8. Sehen Sie sich die Cloud Run-Preise an oder schätzen Sie die Kosten mit dem Preisrechner.

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

MCP-Server, die Server-Sent Events (SSE) oder 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 (normalerweise 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 auf einem bestimmten Port auf HTTP-Anfragen warten. Sie entsprechen also dem Container-Laufzeitvertrag von Cloud Run und können in einem Cloud Run-Dienst bereitgestellt werden.

Wenn Sie einen MCP-Server bereitstellen möchten, der als Container-Image verpackt ist, benötigen Sie die URL des Container-Images und den Port, über den er Anfragen empfangen soll. 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, den es ü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 der MCP-Server eine HTTPS-URL und die Kommunikation kann die integrierte Unterstützung von Cloud Run für HTTP-Antwort-Streaming nutzen.

MCP-Clients für KI-Agenten authentifizieren

Je nachdem, wo Sie den MCP-Client gehostet haben, finden Sie im entsprechenden Abschnitt weitere Informationen:

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 zur Authentifizierung.

IAM-Aufruferberechtigung

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 freizugeben:

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-Proxybefehl 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 Attribut url nicht unterstützt, verwenden Sie das npm-Paket mcp-remote:

{
  "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 Methode 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 Auth-Bibliothek für Python. Dieses Token muss die richtige Zielgruppenanforderung haben, 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.

Lokale MCP-Clients mit IAP authentifizieren

In diesem Abschnitt wird beschrieben, wie Sie lokale MCP-Clients authentifizieren, die in Cloud Run ausgeführt werden.

So erstellen Sie die Richtlinie für eingehenden Traffic:

  1. Weisen Sie dem IAP-Dienst-Agent die Rolle „Cloud Run-Aufrufer“ (roles/run.invoker) zu.

    gcloud run services add-iam-policy-binding SERVICE_NAME \
    --member='serviceAccount:service-PROJECT_NUMBER@gcp-sa-iap.iam.gserviceaccount.com' \
    --role='roles/run.invoker'

    Ersetzen Sie Folgendes:

    • SERVICE_NAME: der Name des Dienstes, dem die Richtlinienbindung hinzugefügt werden soll

    • PROJECT_NUMBER: die Projektnummer des Projekts, das den Dienst enthält

  2. Aktivieren Sie IAP für den Cloud Run-Dienst.

    Erstellen

    Führen Sie den folgenden Befehl aus, um die IAP-Authentifizierung für einen neuen Dienst zu aktivieren:

    gcloud run deploy SERVICE_NAME --image=MCP_SERVER_IMAGE
  --functional-type=MCP_SERVER \
  --region=REGION \
  --iap

    Ersetzen Sie Folgendes:

    • SERVICE_NAME: der Name des Dienstes, dem die Richtlinienbindung hinzugefügt werden soll

    • MCP_SERVER_IMAGE: der Pfad des MCP-Server-Images

    • REGION: die Google Cloud Region, in der Sie Ihren Dienst bereitstellen möchten, z. B. europe-west1

    Aktualisieren

    Führen Sie den folgenden Befehl aus, um die IAP-Authentifizierung für einen vorhandenen Dienst zu aktivieren:

    gcloud run services update SERVICE_NAME \
  --region=REGION \
  --functional-type=MCP_SERVER \
  --iap

    Ersetzen Sie Folgendes:

    • SERVICE_NAME: der Name des Dienstes, der aktualisiert werden soll

    • REGION: die Google Cloud Region, in der Sie Ihren Dienst bereitgestellt haben, z. B. europe-west1

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, auf 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-Authentifizierung

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

Cloud Service Mesh verwenden

Ein Agent, der einen MCP-Client hostet, kann über Cloud Service Mesh eine Verbindung zu einem Remote-MCP-Server herstellen. Die Verwendung eines Service Mesh vereinfacht die Orchestrierung von Mikrodiensten, da Authentifizierung und Traffic-Verwaltung automatisch erfolgen.

Sie können den MCP-Serverdienst so konfigurieren, dass er im Mesh-Netzwerk einen Kurznamen 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