Erste Schritte mit Apigee und MCP

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Auf dieser Seite wird beschrieben, wie Sie den Apigee Discovery-Proxy verwenden, um Ihre APIs für MCP-Clients (Model Context Protocol) in agentischen Anwendungen als MCP-Tools verfügbar zu machen.

Hinweis

Führen Sie die folgenden Aufgaben aus, bevor Sie beginnen:

  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. Prüfen Sie, ob eine Apigee-Organisation bereitgestellt wurde. Der MCP Discovery-Proxy ist für Abo-, „Pay as you go“- und Evaluierungsorganisationen sowie für Apigee Hybrid-Versionen ab 1.17.0 verfügbar. Weitere Informationen finden Sie unter Einführung in die Bereitstellung.
  7. Nur Apigee Hybrid: Prüfen Sie, ob Sie die Schritte zur einmaligen Clusteraktivierung ausgeführt haben, die unter MCP in Apigee Hybrid aktivieren beschrieben sind. Dazu legen Sie enableMcpServer: true als Schlüssel auf oberster Ebene in Ihrer overrides.yaml fest und führen helm upgrade für die Diagramme apigee-operator und apigee-org aus.
  8. Prüfen Sie, ob in Ihrem Projekt in Google Cloud eine Apigee API-Hub-Instanz bereitgestellt ist. Weitere Informationen finden Sie unter API-Hub in der Google Cloud Console bereitstellen. Sie können prüfen, ob der API-Hub-Dienst aktiviert ist, indem Sie die Seite Hub in der Google Cloud Console aufrufen.

    Zum API-Hub

  9. Prüfen Sie, ob eine Apigee-Instanz an Ihren API-Hub-Dienst angehängt ist. Der MCP Discovery-Proxy wird nicht für die Verwendung mit Apigee Edge for Public Cloud- oder Apigee Edge for Private Cloud-Plug-in-Instanzen im API-Hub unterstützt. Weitere Informationen finden Sie unter Laufzeitprojekt anhängen. Sie können den Status des angehängten Laufzeitprojekts in der Google Cloud Console auf der Seite Einstellungen auf dem Tab Projektverknüpfungen prüfen.

    Zum API-Hub

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Apigee-Administrator (roles/apigee.admin) für das Dienstkonto zuzuweisen, mit dem Sie Apigee-Proxys bereitstellen, um die Berechtigungen zu erhalten, die Sie zum Erstellen und Bereitstellen eines MCP-Discovery-Proxys benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

APIs aktivieren

Aktivieren Sie die Apigee API, falls sie noch nicht aktiviert ist.

Erforderliche Rollen zum Aktivieren von APIs

Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Inhaberrolle (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

API aktivieren

Umgebungsvariablen festlegen

Verwenden Sie im Projekt Google Cloud , das Ihre Apigee-Instanz enthält, den folgenden Befehl, um Umgebungsvariablen festzulegen: 

export PROJECT_ID=PROJECT_ID
export REGION=REGION
export RUNTIME_HOSTNAME=RUNTIME_HOSTNAME

Wobei:

  • PROJECT_ID ist die ID des Projekts mit Ihrer Apigee-Instanz.
  • REGION ist die Google Cloud -Region Ihrer Apigee-Instanz. Bei Apigee Hybrid ist dies die Region, in der sich Ihr Cluster befindet.
  • RUNTIME_HOSTNAME ist der Hostname Ihrer Apigee-Laufzeit. Bei Apigee Hybrid ist dies der Hostname, der in Ihrer Apigee-Umgebungsgruppe registriert ist und von Ihrem Apigee-Ingress-Gateway bereitgestellt wird (z. B. api.example.com).

Führen Sie den folgenden Befehl aus und prüfen Sie die Ausgabe, um zu bestätigen, dass die Umgebungsvariablen richtig festgelegt sind: 

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

Projekt festlegen

Legen Sie das Projekt Google Cloud in Ihrer Entwicklungsumgebung fest: 

    gcloud auth login
    gcloud config set project $PROJECT_ID

Übersicht

Wenn Sie Ihre APIs mit Apigee als MCP-Tools bereitstellen möchten, erstellen Sie einen neuen Apigee-Proxy mit der Vorlage MCP Discovery Proxy und stellen ihn bereit. Nachdem Ihr Proxy bereitgestellt wurde, können Sie ein API-Produkt erstellen, um die MCP API-Vorgänge in Ihrem Proxy in einem API-Produkt zu bündeln. Als API-Produkt können Ihre API-Vorgänge und ‑Tools von MCP-Clients über die Einbindung in den API-Hub gefunden werden.

In den folgenden Abschnitten werden die Schritte zum Erstellen und Bereitstellen eines MCP Discovery-Proxys, zum Erstellen eines API-Produkts und zum Auflisten verfügbarer Tools beschrieben:

  1. Erstellen Sie eine OpenAPI 3.0.x-Spezifikation, die Ihre API-Vorgänge beschreibt.
  2. MCP-Discovery-Proxy erstellen
  3. (Optional) Fügen Sie dem MCP-Discovery-Proxy eine Sicherheitsrichtlinie hinzu.
  4. MCP-Discovery-Proxy bereitstellen
  5. (Optional) MCP-Server initialisieren
  6. Verfügbare Tools auflisten

Erstellen Sie eine OpenAPI 3.0.x-Spezifikation, die Ihre API-Vorgänge beschreibt.

Bevor Sie Ihren MCP-Discovery-Proxy erstellen und bereitstellen, müssen Sie eine OpenAPI 3.0.x-Spezifikation erstellen, die die API-Vorgänge beschreibt, die Sie als MCP-Tools verfügbar machen möchten. MCP in Apigee unterstützt die folgenden OpenAPI-Versionen:

  • 3.0.0
  • 3.0.1
  • 3.0.2
  • 3.0.3

In dieser Kurzanleitung wird eine OpenAPI 3.0.x-Beispielspezifikation mit drei API-Vorgängen verwendet:

  • GET /artists: Gibt eine Liste von Künstlern zurück.
  • POST /artists: Ermöglicht es einem Nutzer, einen neuen Künstler zu posten.
  • GET /artists/{username}: Ruft Informationen zu einem Künstler anhand seines eindeutigen Nutzernamens ab.

So erstellen Sie die OpenAPI 3.0.x-Spezifikation:

  1. Erstellen Sie eine neue mcp-quickstart-openapi.yaml-Datei im Verzeichnis oas Ihres API-Proxy-Bundles.
  2. Fügen Sie der Datei den folgenden Inhalt hinzu. 
    # mcp-quickstart-openapi.yaml
---
openapi: 3.0.3
info:
  title: Cymbal Group Products API
  description: This is the official API for managing the artists for Cymbal Group Products.
  version: 1.0.0
servers:
  - url: https://cymbal.products.com
    description: Cymbal Group Production Server
  - url: https://internal.products.com
    description: Cymbal Group internal Server
paths:
  /artists:
    get:
      description: Returns a list of artists
      operationId: listArtists
      parameters:
        - name: limit
          in: query
          description: Limits the number of items on a page
          schema:
            type: integer
        - name: offset
          in: query
          description: Specifies the page number of the artists to be displayed
          schema:
            type: integer
      responses:
        "200":
          description: An array of artists
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Artist"
    post:
      summary: Create a new artist
      operationId: createArtist
      tags:
        - artists
      requestBody:
        description: The artist to create.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Artist"
      responses:
        "201":
          description: The newly created artist profile
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Artist"
        "400":
          description: Invalid username supplied
  /artists/{username}:
    get:
      summary: Info for a specific artist
      operationId: showArtistByUsername
      tags:
        - artists
      parameters:
        - name: username
          in: path
          required: true
          description: The username of the artist to retrieve
          schema:
            type: string
      responses:
        "200":
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Artist"
        "404":
          description: Artist not found
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes:
            artists.read: Grants read access
            artists.write: Grants write access
  schemas:
    Artist:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the artist

Anforderung für Hostnamenabgleich

Der Wert des Hostnamens im Feld servers.url der OpenAPI-Spezifikation muss genau mit dem Hostnamen der Umgebungsgruppe der Apigee-Umgebung übereinstimmen, in der der MCP Discovery Proxy bereitgestellt wird. Diese Übereinstimmung ist erforderlich, damit die Aufrufe tools/list und tools/call richtig funktionieren.

In der folgenden Tabelle sehen Sie die Hostnamenkonfiguration in der OpenAPI-Spezifikation und die entsprechende Hostnamenkonfiguration in der Apigee-Umgebungsgruppe:

Komponente Erforderliche Konfiguration Beispielwert Ergänzende Hinweise
Apigee-Umgebungsgruppe Hostnamen müssen in der Umgebungsgruppe konfiguriert werden. cymbal.products.com, internal.products.com Umgebungsgruppen ermöglichen das Routing zu einer Gruppe von Umgebungen über einen Hostnamen.
OpenAPI-Spezifikation Der Wert des Felds servers.url der OpenAPI-Spezifikation muss genau mit dem Hostnamen der Umgebungsgruppe der Apigee-Umgebung übereinstimmen, in der der MCP Discovery Proxy bereitgestellt wird. https://cymbal.products.com Wenn der Hostname servers.url nicht mit dem Hostnamen der Umgebungsgruppe übereinstimmt, die der Apigee-Umgebung entspricht, in der der MCP Discovery-Proxy bereitgestellt wird, erhalten Sie beim Bereitstellen des Proxys einen Fehler.

MCP-Discovery-Proxy erstellen

Nachdem Sie eine OpenAPI 3.0.x-Spezifikation für Ihre API-Vorgänge definiert haben, können Sie mit der Vorlage MCP Discovery Proxy einen neuen API-Proxy erstellen.

So erstellen Sie einen MCP-Discovery-Proxy:

  1. Rufen Sie in der Google Cloud Console die Seite API-Proxys auf.

    Zu „API-Proxys“

  2. Klicken Sie auf + Erstellen, um den Bereich API-Proxy erstellen zu öffnen.
  3. Wählen Sie im Feld Proxy-Vorlage die Option MCP-Discovery-Proxy aus.
  4. Geben Sie im Abschnitt Proxydetails die folgenden Details ein:
    • Proxyname: Ein Name für Ihren Proxy.
    • Beschreibung (optional): Eine Beschreibung für Ihren Proxy. Beispiel: My first MCP Discovery Proxy.
  5. Klicken Sie auf Weiter.
  6. Wählen Sie im Abschnitt OpenAPI-Spezifikationen mit dem Dateibrowser die OpenAPI 3.0.x-Datei aus, die Sie im vorherigen Schritt erstellt haben.
  7. Klicken Sie auf Weiter.
  8. Im Abschnitt Bereitstellen (optional) können Sie die Bereitstellung des Proxys vorerst überspringen. Klicken Sie auf Weiter.
  9. Klicken Sie auf Erstellen.

Sie können die Ziel- und Serverendpunkte des Proxys aufrufen, indem Sie in der Tabelle Überarbeitungen in der Spalte Endpunktzusammenfassung auf Anzeigen klicken. In der Zusammenfassung der Versionsendpunkte für die ausgewählte Proxy-Version werden die folgenden Informationen angezeigt:

  • Proxy-Endpunkte: In diesem Beispiel wird der Proxy-Endpunkt default mit dem Basispfad /mcp angezeigt. Wenn dem Proxy zusätzliche Hostnamen oder Umgebungsgruppen hinzugefügt werden, werden diese ebenfalls hier angezeigt.
  • Zielendpunkte: In diesem Beispiel ist die Zielverbindung default auf ORG_NAME.mcp.apigee.internal festgelegt, wobei ORG_NAME der Name Ihrer Apigee-Organisation ist. Das Ziel mcp.apigee.internal wird auch aus Gründen der Abwärtskompatibilität unterstützt.

(Optional) Sicherheitsrichtlinie zum MCP-Discovery-Proxy hinzufügen

Bevor Sie Ihren MCP Discovery Proxy bereitstellen, können Sie Sicherheitsrichtlinien hinzufügen, um Sicherheitsanforderungen durchzusetzen. Wir empfehlen, den Zugriff auf Ihren MCP-Discovery-Proxy mit OAuth-Tokens oder einem API-Schlüssel zu sichern.

In diesem Abschnitt wird beschrieben, wie Sie dem MCP-Discovery-Proxy eine OAuthV2-Richtlinie hinzufügen. So wird sichergestellt, dass alle Anfragen an den MCP-Discovery-Proxy authentifiziert und autorisiert werden. Wenn Sie stattdessen einen API-Schlüssel verwenden möchten, finden Sie unter API durch Anfordern von API-Schlüsseln sichern die empfohlenen Schritte.

Wenn Sie die Tokenüberprüfung konfigurieren möchten, platzieren Sie eine OAuthV2-Richtlinie mit dem Vorgang VerifyAccessToken ganz am Anfang des API-Proxy-Ablaufs (am Anfang des ProxyEndpoint-PreFlows). Wenn sie dort platziert werden, werden Zugriffstokens überprüft, bevor eine andere Verarbeitung stattfindet. Wenn ein Token abgelehnt wird, beendet Apigee die Verarbeitung und gibt einen Fehler an den Client zurück.

So fügen Sie die VerifyAccessToken-Richtlinie hinzu:

  1. Klicken Sie auf der Proxy-Detailseite auf den Tab Entwickeln.
  2. Klicken Sie unter Proxy-Endpunkte auf Standard und dann auf PreFlow.

  3. Klicken Sie im Proxy-Flow-Editor auf Richtlinienschritt hinzufügen.

    PreFlow für einen Endpunkt unter "Proxy-Endpunkte" auswählen
  4. Wählen Sie im Dialogfeld Richtlinienschritt hinzufügen die Option Neue Richtlinie erstellen aus.
  5. Wählen Sie in der Richtlinienliste unter Sicherheit die Option OAuth v2.0 aus.
  6. Optional haben Sie die Möglichkeit, den Richtliniennamen und den Anzeigenamen zu ändern. Beispielsweise können Sie zur besseren Lesbarkeit sowohl den Anzeigenamen als auch den Namen in VerifyAccessToken ändern.
  7. Klicken Sie auf Hinzufügen.

MCP-Discovery-Proxy bereitstellen

So stellen Sie den MCP-Discovery-Proxy bereit:

  1. Klicken Sie auf Bereitstellen, um den Bereich API-Proxy bereitstellen zu öffnen.
  2. Das Feld Überarbeitung sollte auf 1 festgelegt sein. Falls nicht, klicken Sie auf 1, um sie auszuwählen.
  3. Wählen Sie in der Liste Umgebung die Umgebung aus, in der Sie den Proxy bereitstellen möchten. Die Umgebung muss eine umfassende Umgebung sein.
  4. Geben Sie das Dienstkonto ein, das Sie in einem vorherigen Schritt erstellt haben.
  5. Klicken Sie auf Bereitstellen.

Wenn Sie auf Bereitstellen klicken, beginnt Apigee mit der Bereitstellung des Proxys und der Bereitstellung von Downstream-Komponenten. Während dieser Zeit, die mehrere Minuten dauern kann, wird in der Benutzeroberfläche der Status Wird bereitgestellt für die Bereitstellung angezeigt.

Wenn der Vorgang abgeschlossen ist, ändert sich der Status in Bereitgestellt und der Proxy ist bereit, Traffic zu verarbeiten.

Prüfen Sie nach der Bereitstellung des Proxys, ob der Wert des Hostnamens im Feld servers.url der OpenAPI-Spezifikation genau mit dem Hostnamen der Umgebungsgruppe der Apigee-Umgebung übereinstimmt, in der der MCP-Discovery-Proxy bereitgestellt wird.

MCP-Tools im API-Hub entdecken

Nachdem Ihr MCP-Discovery-Proxy bereitgestellt wurde, werden seine API-Vorgänge automatisch in den API-Hub aufgenommen und als MCP-Tools auffindbar gemacht.

So rufen Sie Ihre MCP-Tools im API-Hub auf:

  1. Rufen Sie in der Google Cloud Console die Seite API-Hub > APIs auf.

    Zu den API-Hub-APIs

  2. Klicken Sie auf Filter, wählen Sie Stil > MCP aus und klicken Sie dann auf Übernehmen.
  3. Der bereitgestellte MCP-Proxy sollte in der Liste angezeigt werden. Die API-Hub-Aufnahmepipeline ordnet die in Ihrer OpenAPI-Spezifikation definierten Pfade automatisch den einzelnen MCP-Tools zu, die im Hub aufgeführt sind.

Entwickler in Ihrer Organisation können jetzt Filter oder die semantische Suche im API-Hub verwenden, um relevante MCP-Tools mithilfe von Abfragen in natürlicher Sprache zu finden.

MCP-Server initialisieren

In diesem Schritt senden Sie eine Anfrage an Ihren MCP-Endpunkt, um Ihren MCP-Server zu initialisieren und zu bestätigen, dass er wie erwartet funktioniert.

Senden Sie die folgende Anfrage an Ihren MCP-Endpunkt, um Ihren MCP-Server zu initialisieren und zu testen: 

curl -X POST "https://MCP_ENDPOINT_URL/mcp" \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": 1,
        "method": "initialize",
        "params": {
          "protocolVersion": "MCP_PROTOCOL_VERSION"
        }
      }' \
  -H "Authorization: Bearer TOKEN"

Ersetzen Sie Folgendes:

  • MCP_ENDPOINT_URL: der Basis-URI Ihres MCP-Endpunkts. Beispiel: cymbal.products.com.
  • MCP_PROTOCOL_VERSION: die MCP-Protokollversion. Beispiel: 2025-11-25. Weitere Informationen finden Sie in der MCP-Spezifikation unter Versionsverhandlung.
  • (Optional) TOKEN: OAuth 2.0-Zugriffstoken

Eine erfolgreiche Antwort sieht in etwa so aus:

{
"id":1,
"jsonrpc":"2.0",
"result":
  {
    "capabilities":
    {
      "tools":
      {
        "listChanged":false
      }
    },
    "protocolVersion":"2025-11-25",
    "serverInfo":
      {
        "name":"cymbal.products.com",
        "version":"1.0.0"
      }
    }
  }

Verfügbare MCP-Tools auflisten

In diesem Schritt senden Sie eine Anfrage an die Methode tools/list, um die Liste der in Ihrem MCP-Endpunkt verfügbaren Tools zu bestätigen.

Senden Sie eine Anfrage an die tools/list-Methode für Ihren Apigee-Proxy:

curl -X POST "https://MCP_ENDPOINT_URL/mcp" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: MCP_PROTOCOL_VERSION" \
  -d '{
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/list",
        "params": {}
      }' \
  -H "Authorization: Bearer TOKEN"

Ersetzen Sie Folgendes:

  • MCP_ENDPOINT_URL: der Basis-URI Ihres MCP-Endpunkts. Beispiel: cymbal.products.com.
  • MCP_PROTOCOL_VERSION: die MCP-Protokollversion. Beispiel: 2025-11-25. Weitere Informationen finden Sie in der MCP-Spezifikation unter Protocol version header.
  • (Optional) TOKEN: OAuth 2.0-Zugriffstoken

Die Methode gibt alle Tools zurück, die der MCP-Endpunkt unterstützt. Eine erfolgreiche Antwort sieht in etwa so aus:

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "description": "Returns a list of artists",
        "inputSchema": {
          "properties": {
            "id": {
              "description": "Unique identifier for the artist",
              "format": "uuid",
              "type": "string"
            }
          },
          "type": "object"
        },
        "name": "listArtists"
      },
      {
        "description": "Create a new artist",
        "inputSchema": {
          "properties": {
            "id": {
              "description": "Unique identifier for the artist",
              "format": "uuid",
              "type": "string"
            }
          },
          "type": "object"
        },
        "name": "createArtist"
      },
      {
        "description": "Info for a specific artist",
        "inputSchema": {
          "properties": {
            "id": {
              "description": "Unique identifier for the artist",
              "format": "uuid",
              "type": "string"
            }
          },
          "type": "object"
        },
        "name": "showArtistByUsername"
      }
    ]
  }
}

Nachdem Ihr Endpunkt initialisiert wurde, können Entwickler und KI-Agenten, die Ihr API-Produkt verwenden, Ihre MCP-Tools finden.

Monitoring und Analysen

Mit Apigee Analytics können Sie den MCP-Traffic überwachen und Messwerte auf Toolebene aufrufen. Mit Apigee Analytics können Sie Messwerte filtern, um zwischen Standard-API-Traffic und MCP-spezifischem Traffic zu unterscheiden und das Nutzungsvolumen für tools/list- und tools/call-Anfragen zu sehen. Weitere Informationen finden Sie unter MCP-Traffic in Apigee überwachen und analysieren.

Nächste Schritte