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.
• 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 x-google-mcp-tool-Erweiterung darf nur auf der Ebene des einzelnen Vorgangs angegeben werden.
• HTTP-Methode: Nur Vorgänge vom Typ GET, POST, PUT, PATCH und DELETE 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, die aus der Beschreibung, Zusammenfassung oder Überschreibung des Vorgangs stammt. Vorgänge ohne eine 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-Schema oder ein API-Schlüsselschema sein. Wenn Sie ein JWT-Schema verwenden, müssen Sie es auch in der security-Anforderung 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.
• 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 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 von MCP

So machen Sie Ihre API als MCP-Tool verfügbar:

1. Zu veröffentlichende 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. tools/list authentifizieren (empfohlen)

Standardmäßig ist die Methode tools/list (mit der verfügbare Tools aufgelistet werden) 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 benennen.

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 x-api-key-HTTP-Header senden. tools/list liest API-Schlüssel nicht aus Suchparametern. Bei einer Anfrage ohne gültigen Schlüssel wird ein JSON-RPC-Fehler zurückgegeben und es wird keine Toolliste bereitgestellt. 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 in einem Gateway bereit. Weitere Informationen finden Sie unter API in 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 Wenn Sie tools-list.security konfiguriert haben, fügen Sie die entsprechende 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 anhand der OpenAPI-Spezifikation der zugrunde liegenden REST-Anfrage zugeordnet:

• Pfad- und Suchparameter: Sie 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 Backend-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 liefern Standardmesswerte 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

MCP unterscheidet zwischen Transport- und Protokollfehlern. 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:

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

Nächste Schritte

• Model Context Protocol – Übersicht
• OpenAPI 3.x-Erweiterungen
• Einschränkungen von OpenAPI 3.x-Funktionen