Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Model Context Protocol konfigurieren

In diesem Dokument wird beschrieben, wie Sie API Gateway als Remote-MCP-Server (Model Context Protocol) konfigurieren.

Hinweis

Sie benötigen eine gültige OpenAPI 3.x-Spezifikation für Ihre API. MCP wird für OpenAPI 2.0 nicht unterstützt.
Machen Sie sich mit den Grundlagen von API Gateway vertraut.

Konfigurationsprüfung

Wenn Sie Ihre OpenAPI-Spezifikation hochladen, führt API Gateway die folgenden Validierungen für die MCP-Konfiguration durch:

Standort: Die Erweiterung x-google-mcp-tool darf nur auf der Ebene einzelner Vorgänge angegeben werden.
HTTP-Methode: Nur GET-, POST-, PUT-, PATCH- und DELETE-Vorgänge können als MCP-Tools bereitgestellt werden.
Toolname: Toolnamen müssen mit [A-Za-z0-9_.-]{1,128} übereinstimmen und in der gesamten Spezifikation eindeutig sein.
Beschreibung: Jedes Tool muss eine nicht leere Beschreibung haben (aus der Beschreibung, Zusammenfassung oder Überschreibung des Vorgangs). Vorgänge ohne auflösbare Beschreibung werden abgelehnt.
Sicherheit: Wenn Sie die Authentifizierung für tools/list konfigurieren, müssen Sie genau ein Sicherheitsschema angeben, das unter components.securitySchemes definiert ist. Das Schema kann ein JWT- oder ein API-Schlüsselschema sein. Wenn Sie ein JWT-Schema verwenden, müssen Sie es auch in der Anforderung security auf oberster Ebene der Spezifikation benennen.

Authentifizierungsmodell

API Gateway wendet je nach aufgerufener MCP-Methode unterschiedliche Authentifizierungsregeln an:

Protokolllebenszyklus: Die Methoden initialize und notifications/initialized sind nicht authentifiziert.
Toolaufruf (tools/call): Verwendet die Authentifizierungsrichtlinien wieder, die für den zugrunde liegenden Vorgang in Ihrer OpenAPI-Spezifikation definiert sind. Es gelten dieselben API-Schlüssel- oder JWT-Anforderungen wie beim direkten Aufruf des REST-Endpunkts.
Tool Discovery (tools/list): Diese Methode ist standardmäßig nicht authentifiziert. Als Best Practice für die Sicherheit empfehlen wir jedoch dringend, die Tool-Erkennung zu schützen, indem Sie die Authentifizierung für diese Methode mit tools-list.security aktivieren. Sie können tools/list entweder mit einem JWT oder einem API-Schlüssel authentifizieren.

Schritte zum Konfigurieren des MCP

So stellen Sie Ihre API als MCP-Tools bereit:

1. Vorgänge identifizieren, die verfügbar gemacht werden sollen

Überprüfen Sie Ihre OpenAPI-Spezifikation und entscheiden Sie, welche Vorgänge für KI-Agenten verfügbar sein sollen.

2. OpenAPI-Spezifikation aktualisieren

Sie können MCP global für alle infrage kommenden Vorgänge aktivieren oder pro Vorgang konfigurieren.

Globale Aktivierung

Aktivieren Sie MCP global, indem Sie das Feld mcp auf Dokumentebene zu x-google-api-management hinzufügen:

openapi: 3.0.3
info:
  title: Bookstore API
  version: 1.0.0
x-google-api-management:
  mcp: true
  backends:
    bookstore-backend:
      address: https://bookstore-backend-12345678.us-central1.run.app

Wenn diese Option global aktiviert ist, werden alle infrage kommenden Vorgänge (basierend auf HTTP-Methode und Pfad) als MCP-Tools bereitgestellt. Standardmäßig ist der Toolname die operationId des Vorgangs und die Beschreibung ist die Beschreibung oder Zusammenfassung des Vorgangs.

Vorgangsspezifische Konfiguration

Sie können globale Einstellungen überschreiben oder Vorgänge selektiv mit x-google-mcp-tool verfügbar machen:

paths:
  /v1/shelves/{shelf}:
    delete:
      operationId: deleteShelf
      summary: Delete a shelf.
      x-google-backend: bookstore-backend
      x-google-mcp-tool:
        name: delete_shelf
        description: "Permanently delete a shelf and every book on it."

Sie können einen Vorgang auch deaktivieren, wenn er global aktiviert ist, indem Sie x-google-mcp-tool: false festlegen.

3. `tools/list` authentifizieren (empfohlen)

Standardmäßig ist die Methode tools/list (die verfügbare Tools auflistet) nicht authentifiziert. Als Best Practice für die Sicherheit empfehlen wir dringend, die Authentifizierung zu erzwingen, indem Sie tools-list.security unter x-google-api-management.mcp konfigurieren. Sie können entweder ein JWT-Schema oder ein API-Schlüsselschema angeben.

Im folgenden Beispiel ist ein JWT erforderlich:

x-google-api-management:
  mcp:
    tools-list:
      security:
        myJWT: []

Für das folgende Beispiel ist ein API-Schlüssel erforderlich. Clients müssen den Schlüssel im HTTP-Header x-api-key senden. tools/list liest keine API-Schlüssel aus Suchparametern. Eine Anfrage ohne gültigen Schlüssel erhält einen JSON-RPC-Fehler und keine Toolliste. Informationen zum Erstellen eines API-Schlüssels finden Sie unter API-Schlüssel verwenden.

x-google-api-management:
  mcp:
    tools-list:
      security:
        api_key: []
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header

4. API-Konfiguration erstellen und bereitstellen

Erstellen Sie eine API-Konfiguration aus Ihrer annotierten Spezifikation und stellen Sie sie über den Standardablauf auf einem Gateway bereit. Weitere Informationen finden Sie unter API auf einem Gateway bereitstellen. Informationen zum späteren Ändern von Tools finden Sie unter Verfügbare MCP-Tools aktualisieren.

5. MCP-Unterstützung prüfen

Nach der Bereitstellung können Sie prüfen, ob das Gateway MCP-Anfragen verarbeitet.

Handshake

Senden Sie eine Initialisierungsanfrage, um die Protokollversion und die Funktionen festzulegen:

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {"name": "demo-client", "version": "1.0.0"}
  }
}'

Handshake bestätigen

Bestätigen Sie die Initialisierung. Das Gateway antwortet mit HTTP 202 Accepted:

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}'

Tools entdecken

Listen Sie die verfügbaren Tools auf. Wenn Sie tools-list.security konfiguriert haben, fügen Sie die entsprechenden Anmeldedaten hinzu, z. B. einen Authorization: Bearer-Header für ein JWT oder einen x-api-key-Header für einen API-Schlüssel:

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

Zuordnung von Argumenten zur REST-Anfrage

Die an ein Tool übergebenen Argumente werden basierend auf der OpenAPI-Spezifikation der zugrunde liegenden REST-Anfrage zugeordnet:

Pfad- und Suchparameter: Werden zu Attributen auf oberster Ebene im arguments-Objekt, die nach ihren OpenAPI-Parameternamen sortiert sind.
Anfragetext: Verschachtelt unter einer einzelnen Property namens body. Wenn Sie beispielsweise eine Ressource erstellen möchten, übergeben Sie {"body": {"fieldName": "value"}}.
Header: Werden ebenfalls zu Attributen der obersten Ebene. Das Gateway fügt sie als Standard-HTTP-Header in den Backend-Aufruf ein.

Die transcodierte Backend-Anfrage ist nicht von einer direkten REST-Anfrage an Ihren Backend-Dienst zu unterscheiden. Backend-Dienste können programmatisch nicht zwischen einem direkten REST-Aufruf und einem von MCP transcodierten Aufruf unterscheiden.

Tool aufrufen

Ein bestimmtes Tool aufrufen. Achten Sie darauf, alle erforderlichen Authentifizierungstokens anzugeben, wenn der zugrunde liegende REST-Vorgang diese erfordert:

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "delete_shelf",
    "arguments": {"shelf": "sci-fi"}
  }
}'

Verfügbare MCP-Tools aktualisieren

API-Konfigurationen in API Gateway sind unveränderlich. Sie können die API-Definition in einer vorhandenen API-Konfiguration also nicht ändern. Daher ist die tools/list-Antwort für jede bereitgestellte API-Konfiguration statisch.

Wenn Sie freigegebene MCP-Tools oder tools/list-Sicherheitseinstellungen hinzufügen, entfernen, umbenennen oder aktualisieren möchten, erstellen Sie eine neue API-Konfiguration und stellen Sie sie auf Ihrem Gateway bereit:

Aktualisieren Sie Ihre OpenAPI 3.x-Spezifikation, einschließlich Vorgängen, operationId-Werten, Zusammenfassungen, Parametern und den Erweiterungen x-google-api-management.mcp und x-google-mcp-tool.
Erstellen Sie eine neue API-Konfiguration mit einer neuen API-Konfigurations-ID:
```
gcloud api-gateway api-configs create NEW_CONFIG_ID \
    --api=API_ID \
    --openapi-spec=API_DEFINITION \
    --project=PROJECT_ID \
    --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
```
Ersetzen Sie Folgendes:
- NEW_CONFIG_ID: eine neue ID für die aktualisierte API-Konfiguration
- API_ID: die ID der API Gateway API
- API_DEFINITION: der Pfad zu Ihrer aktualisierten OpenAPI 3.x-Spezifikation
- PROJECT_ID: Ihre Projekt-ID in Google Cloud
- SERVICE_ACCOUNT_EMAIL: die E-Mail-Adresse des Dienstkontos, das zum Signieren von Tokens für Back-Ends mit konfigurierter Authentifizierung verwendet wird. Lassen Sie dieses Flag weg, wenn für keines Ihrer Back-Ends eine Authentifizierung erforderlich ist.
Weitere Informationen finden Sie unter API-Konfiguration erstellen.
Aktualisieren Sie jedes Gateway, das die API bereitstellt, um die neue API-Konfiguration zu verwenden:
```
gcloud api-gateway gateways update GATEWAY_ID \
    --api=API_ID \
    --api-config=NEW_CONFIG_ID \
    --location=GCP_REGION \
    --project=PROJECT_ID
```
Ersetzen Sie Folgendes:
- GATEWAY_ID: die ID des Gateways, das aktualisiert werden soll
- GCP_REGION: die Region, in der das Gateway bereitgestellt wird
Weitere Informationen finden Sie unter Gateway aktualisieren.
Rufen Sie tools/list auf, um das aktualisierte Toolset zu prüfen. Eine Beispielanfrage finden Sie unter Tools entdecken.
Wenn kein Gateway mehr die vorherige API-Konfiguration verwendet, löschen Sie die ersetzte API-Konfiguration:
```
gcloud api-gateway api-configs delete OLD_CONFIG_ID \
    --api=API_ID \
    --project=PROJECT_ID
```
Ersetzen Sie OLD_CONFIG_ID durch die ID der ersetzten API-Konfiguration. Löschen Sie eine API-Konfiguration nicht, solange sie noch von einem Gateway verwendet wird. Wenn Sie in Ihrer neuen API-Konfiguration Kontingentmesswerte umbenennen oder entfernen, können Gateways, die noch eine ältere API-Konfiguration bereitstellen, bis zur Aktualisierung HTTP-500-Fehler zurückgeben (siehe Kontingente gelten für die gesamte API). Weitere Informationen finden Sie unter API-Konfiguration löschen.

Beachten Sie beim Aktualisieren von MCP-Tools die folgenden Rollout- und Client-Verhaltensweisen:

Roll-out ohne Ausfallzeiten: API Gateway aktualisiert Gateways ohne Ausfallzeiten. Während die neue API-Konfiguration weitergegeben wird, erreichen einige Anfragen möglicherweise kurzzeitig die vorherige API-Konfiguration. Wenn Ihre API über mehrere Gateways oder Regionen bereitgestellt wird, aktualisieren Sie jedes Gateway separat.
Client-Tool-Caches: Da API Gateway MCP über einen zustandslosen HTTP-Transport bereitstellt, gibt das Gateway keine notifications/tools/list_changed-Benachrichtigungen aus. Nach Abschluss des Gateway-Updates müssen MCP-Clients, die Tooldefinitionen im Cache speichern, tools/list noch einmal aufrufen, um die aktualisierten Tools zu finden.
Limits für API-Konfigurationen: Jede API ist auf 100 API-Konfigurationen beschränkt. Löschen Sie daher nach dem Aktualisieren Ihrer Gateways veraltete API-Konfigurationen. Erstellen Sie API-Konfigurationen nacheinander. Wenn Sie eine zweite API-Konfiguration für dieselbe API starten, bevor die erste abgeschlossen ist, kann eine oder beide möglicherweise nicht von einem Gateway verwendet werden. Weitere Informationen finden Sie unter Kontingente und Limits.

Beobachtbarkeit

MCP-Anfragen liefern Standard-API-Gateway-Messwerte und ‑Logs. Sie können MCP-Traffic von Standard-REST-Traffic unterscheiden, indem Sie den Anfragepfad prüfen (endet normalerweise auf /mcp) oder benutzerdefinierte Messwerte konfigurieren.

Fehlerbehebung bei MCP-Fehlern

MCP unterscheidet zwischen Transportfehlern und Protokollfehlern. Das Gateway gibt bei Protokoll- und Anwendungsfehlern HTTP 200 mit einem JSON-RPC-Fehlerobjekt zurück, da Antworten, die nicht 200 sind, bei vielen MCP-Clients zu Fehlern auf der Transportschicht führen können.

In der folgenden Tabelle werden häufige Symptome und Lösungen beschrieben:

Symptom	JSON-RPC-Code	HTTP-Status	Bedeutung und typische Lösung
Methode nicht zulässig	–	`405`	Eine Nicht-POST-Anfrage hat `/mcp` erreicht. Es wird nur HTTP `POST` unterstützt.
JSON-Parsing-Fehler	`-32700`	`400`	Der Anfragetext ist kein gültiges JSON-Format.
Fehlende/ungültige Methode oder ID	`-32600`	`200`	Der Text ist ein gültiges JSON-Format, aber keine gültige JSON-RPC-Anfrage. Prüfen Sie die Pflichtfelder (`jsonrpc`, `method`, `id`).
Methode wird nicht unterstützt	`-32601`	`200`	Die Methode liegt außerhalb des unterstützten Bereichs (z.B. `ping`).
Nicht unterstützte Protokollversion	`-32602`	`200`	`protocolVersion` benennt eine Version, die vom Gateway nicht unterstützt wird.
Protokollversion fehlt	`-32602`	`200`	In den `initialize`-Parametern fehlt `protocolVersion` oder es ist kein String.
Unbekanntes Tool	`-32602`	`200`	Der Toolname wurde in der bereitgestellten API-Konfiguration nicht gefunden. Aktualisieren Sie den Cache des Client-Tools oder lesen Sie den Abschnitt Bereitgestellte MCP-Tools aktualisieren.
Ungültige Toolargumente	`-32602`	`200`	Argumente fehlen oder sind ungültig. Prüfen Sie die Verschachtelung des Schlüssels `body`.
Text zu lang	`-32000`	`200`	Die Antwortnutzlast hat die Größenbeschränkung überschritten.
Transporttext zu groß	–	`413`	Der HTTP-Anfragetext im Rohformat hat die Gateway-Transportlimits überschritten.
Serverfehler	`-32000`	`200`	Nicht parsbare Backend-Antwort. Logs prüfen
Nicht autorisiert/Verboten	–	`401`/`403`	Authentifizierungsfehler Die Antwort enthält einen `WWW-Authenticate`-Header, der auf Metadaten der geschützten Ressource verweist.

Backend-Anwendungsfehler werden in der Regel als erfolgreiche JSON-RPC-Antwort (HTTP 200) angezeigt, wobei result.isError: true den Backend-Fehlertext enthält.