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 so konfigurieren, dass es als Remote-MCP-Server (Model Context Protocol) fungiert.

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.
Sie sollten die Grundlagen von API Gateway kennen.

Konfigurationsprüfung

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

Speicherort: Die Erweiterung x-google-mcp-tool darf nur auf der Ebene des einzelnen Vorgangs angegeben werden.
HTTP-Methode: Nur GET-, POST-, PUT-, PATCH- und DELETE-Vorgänge können als MCP-Tools bereitgestellt werden.
Tool Name (Tool-Name): Tool-Namen müssen mit [A-Za-z0-9_.-]{1,128} übereinstimmen und in der gesamten Spezifikation eindeutig sein.
Beschreibung: Jedes Tool muss in einer nicht leeren Beschreibung enden (aus der Beschreibung, Zusammenfassung oder Überschreibung des Vorgangs). Vorgänge ohne eine auflösbare Beschreibung werden abgelehnt.
Sicherheit: Wenn Sie die Authentifizierung für tools/list konfigurieren, müssen Sie genau ein JWT-Sicherheitsschema angeben, das unter components.securitySchemes definiert ist. Die API-Schlüsselsicherheit wird für tools/list in der öffentlichen Vorschau nicht unterstützt.

Authentifizierungsmodell

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

Protokolllebenszyklus: Die Methoden initialize und notifications/initialized sind nicht authentifiziert.
Tool-Aufruf (tools/call): Hier werden die Authentifizierungsrichtlinien wiederverwendet, 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 Aufrufen des REST-Endpunkts.
Tool Discovery (tools/list): Standardmäßig ist diese Methode nicht authentifiziert. Als Best Practice für die Sicherheit wird jedoch dringend empfohlen, die Tool-Erkennung zu schützen, indem Sie die Authentifizierung für diese Methode mit tools-list.security aktivieren. Wenn Sie die Authentifizierung aktivieren, müssen Sie ein JWT-Sicherheitsschema verwenden. Die API-Schlüssel-Authentifizierung wird für tools/list nicht unterstützt.

MCP konfigurieren

So stellen Sie Ihre API als MCP-Tools bereit:

1. Zu präsentierende Vorgänge identifizieren

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

2. OpenAPI-Spezifikation aktualisieren

Sie können MCP global für alle infrage kommenden Vorgänge aktivieren oder für jeden Vorgang einzeln 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 die Funktion global aktiviert ist, werden alle infrage kommenden Vorgänge (basierend auf HTTP-Methode und Pfad) als MCP-Tools verfügbar gemacht. Standardmäßig ist der Toolname der operationId des Vorgangs und die Beschreibung die Beschreibung oder Zusammenfassung des Vorgangs.

Konfiguration pro Vorgang

Sie können globale Einstellungen überschreiben oder Vorgänge mit x-google-mcp-tool selektiv 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. Authentifizieren mit `tools/list` (empfohlen)

Standardmäßig ist die Methode tools/list (mit der verfügbare Tools aufgelistet werden) nicht authentifiziert. Als Best Practice für die Sicherheit wird dringend empfohlen, die Authentifizierung zu erzwingen, indem Sie tools-list.security unter x-google-api-management/mcp konfigurieren. Sie müssen ein JWT-Schema verwenden. API-Schlüssel werden für diese Methode nicht unterstützt.

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

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.

5. MCP-Unterstützung prüfen

Nach der Bereitstellung können Sie überprü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

Verfügbare Tools auflisten:

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 anhand der OpenAPI-Spezifikation der zugrunde liegenden REST-Anfrage zugeordnet:

Pfad- und Abfrageparameter: Werden zu Eigenschaften der obersten Ebene im arguments-Objekt, die nach ihren OpenAPI-Parameternamen indexiert werden.
Anfragetext: Verschachtelt unter einer einzelnen Property mit dem Namen 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 transkodierte Back-End-Anfrage ist nicht von einer direkten REST-Anfrage an Ihren Backend-Dienst zu unterscheiden. Back-End-Dienste können programmatisch nicht zwischen einem direkten REST-Aufruf und einem aus MCP transcodierten Aufruf unterscheiden.

Tool aufrufen

Ein bestimmtes Tool aufrufen Achten Sie darauf, dass Sie alle erforderlichen Authentifizierungstokens angeben, wenn der zugrunde liegende REST-Vorgang sie 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"}
  }
}'

Beobachtbarkeit

MCP-Anfragen führen zu Standardmesswerten und ‑logs für API Gateway. Sie können MCP-Traffic von Standard-REST-Traffic unterscheiden, indem Sie den Anfragepfad prüfen (der in der Regel mit /mcp endet) oder benutzerdefinierte Messwerte konfigurieren.

Fehlerbehebung bei MCP-Fehlern

Im MCP wird zwischen Transport- und Protokollfehlern unterschieden. Das Gateway gibt HTTP 200 mit einem JSON-RPC-Fehlerobjekt für Protokoll- und Anwendungsfehler 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 Korrektur
Methode nicht zulässig	–	`405`	Eine Nicht-POST-Anfrage wurde an `/mcp` gesendet. Nur HTTP `POST` wird unterstützt.
JSON-Parsing-Fehler	`-32700`	`400`	Der Anfragetext ist kein gültiges JSON.
Fehlende/ungültige Methode oder ID	`-32600`	`200`	Der Text ist gültiges JSON, aber keine gültige JSON-RPC-Anfrage. Prüfen Sie die Pflichtfelder (`jsonrpc`, `method`, `id`).
Die 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` gibt eine Version an, die vom Gateway nicht unterstützt wird.
Fehlende Protokollversion	`-32602`	`200`	In den `initialize`-Parametern fehlt `protocolVersion` oder es ist kein String.
Unbekanntes Tool	`-32602`	`200`	Der Toolname wurde nicht gefunden. Clientcache leeren oder Bereitstellung überprüfen
Ungültige Toolargumente	`-32602`	`200`	Argumente fehlen oder sind ungültig. Prüfen Sie die `body`-Schlüsselverschachtelung.
Text zu lang	`-32000`	`200`	Die Nutzlast der Antwort hat die Größenbeschränkungen überschritten.
Transportkörper zu groß	–	`413`	Der Roh-HTTP-Anfragetext hat die Transportlimits des Gateways überschritten.
Serverfehler	`-32000`	`200`	Die Backend-Antwort kann nicht geparst werden. Prüfen Sie die Logs.
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) mit result.isError: true angezeigt, die den Backend-Fehlertext enthält.