Erste Schritte mit Apigee und MCP

Diese Seite gilt für Apigee, aber nicht für 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 Agentenanwendungen 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 noch kein Konto haben Google Cloud, erstellen Sie ein Konto, um die Leistung 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 verfügbar für Abo-, Pay-as-you-go- und Testorganisationen. Weitere Informationen finden Sie unter Einführung in die Bereitstellung.
  7. Prüfen Sie, ob in Ihrem Google Cloud Projekt eine Apigee API-Hub-Instanz bereitgestellt wurde. 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 in der Google Cloud Console die Seite Hub aufrufen.

    Zum API-Hub

  8. 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 öffentliche 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 Anhängens von Laufzeitprojekten in der Google Cloud Console auf der Seite Einstellungen auf dem Tab Projektzuordnungen prüfen.

    Zum API-Hub

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen für das Dienstkonto, mit dem Sie Apigee-Proxys bereitstellen, die IAM-Rolle „Apigee-Administrator “ (roles/apigee.admin) zuzuweisen, 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.

Rollen, die zum Aktivieren von APIs erforderlich sind

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 Rolle „Inhaber“ (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

Legen Sie im Google Cloud Projekt mit Ihrer Apigee-Instanz mit dem folgenden Befehl Umgebungsvariablen fest: 

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.
  • RUNTIME_HOSTNAME ist der Hostname Ihrer Apigee-Laufzeit.

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

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

Projekt festlegen

Legen Sie das Google Cloud Projekt in Ihrer Entwicklungsumgebung fest: 

    gcloud auth login
    gcloud config set project $PROJECT_ID

Übersicht

Wenn Sie Ihre APIs mit Apigee als MCP-Tools verfügbar machen möchten, erstellen und stellen Sie einen neuen Apigee-Proxy mit der Vorlage „MCP-Discovery-Proxy“ bereit. Nachdem Ihr Proxy bereitgestellt wurde, können Sie ein API-Produkt erstellen, um die MCP-API-Vorgänge in Ihrem Proxy zu einem API-Produkt zusammenzufassen. Als API-Produkt können MCP-Clients Ihre API-Vorgänge/Tools über die Integration in den API-Hub erkennen.

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

  1. Erstellen Sie eine OpenAPI 3.0.x-Spezifikation, die Ihre API-Vorgänge beschreibt.
  2. Erstellen Sie einen MCP-Discovery-Proxy.
  3. Optional: Fügen Sie dem MCP-Discovery-Proxy eine Sicherheitsrichtlinie hinzu.
  4. Stellen Sie den MCP-Discovery-Proxy bereit.
  5. Optional: Initialisieren Sie Ihren MCP-Server.
  6. Listen Sie die verfügbaren Tools auf.

OpenAPI 3.0.x-Spezifikation erstellen, 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 im Verzeichnis oas Ihres API-Proxy-Bundles eine neue Datei mcp-quickstart-openapi.yaml.
  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 den 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 korrekt funktionieren.

In der folgenden Tabelle ist die Hostnamenkonfiguration in der OpenAPI-Spezifikation und die entsprechende Hostnamenkonfiguration in der Apigee-Umgebungsgruppe dargestellt:

Komponente Erforderliche Konfiguration Beispielwert Ergänzende Hinweise
Apigee-Umgebungsgruppe Hostnamen müssen in der Umgebungsgruppe konfiguriert werden. cymbal.products.com, internal.products.com Mit Umgebungsgruppen kann der Traffic über einen Hostnamen an eine Gruppe von Umgebungen weitergeleitet werden.
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, wird beim Bereitstellen des Proxys ein Fehler ausgegeben.

MCP-Discovery-Proxy erstellen

Nachdem Sie eine OpenAPI 3.0.x-Spezifikation erstellt haben, die Ihre API-Vorgänge definiert, 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 Proxyvorlage die Option MCP-Discovery-Proxy aus.
  4. Geben Sie im Bereich Proxy-Details 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 Bereich OpenAPI-Spezifikationen mit der Dateiauswahl die OpenAPI 3.0.x-Datei aus, die Sie im vorherigen Schritt erstellt haben.
  7. Klicken Sie auf Weiter.
  8. Im Bereich Bereitstellen (optional) können Sie die Bereitstellung Ihres 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 Revisionen in der Spalte Endpunktübersicht auf Anzeigen klicken. In der Endpunktübersicht der Revision für die ausgewählte Proxyrevision werden die folgenden Informationen angezeigt:

  • Proxy-Endpunkte: In diesem Beispiel wird der default Proxy-Endpunkt 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 default Zielverbindung 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: MCP-Discovery-Proxy eine Sicherheitsrichtlinie 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. Dadurch 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 mit API-Schlüsseln sichern die empfohlenen Schritte.

Zur Konfiguration der Tokenverifizierung platzieren Sie eine OAuthV2-Richtlinie mit dem Vorgang VerifyAccessToken an den Anfang des API-Proxy-Ablaufs, also zu Beginn des ProxyEndpoint-PreFlows. Damit werden Zugriffstokens geprü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 Richtlinie „VerifyAccessToken“ 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. Zur besseren Lesbarkeit können Sie beispielsweise den Anzeigenamen und 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 Revision sollte auf 1 festgelegt sein. Wenn nicht, klicken Sie auf 1 , um es 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 früheren 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 Bereitstellung für die Bereitstellung angezeigt.

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

Nachdem der Proxy bereitgestellt wurde, prüfen Sie, 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 erkennen

Sobald Ihr MCP-Discovery-Proxy bereitgestellt wurde, werden seine API-Vorgänge automatisch in den API-Hub aufgenommen und als MCP-Tools erkennbar 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 „API-Hub APIs“

  2. Klicken Sie auf Filter und wählen Sie Stil > MCP aus. Klicken Sie dann auf Übernehmen.
  3. Ihr bereitgestellter MCP-Proxy sollte in der Liste angezeigt werden. Die Aufnahmepipeline des API-Hubs 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 mit Suchanfragen 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 prüfen, ob 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 unter Version Negotiation in der MCP-Spezifikation.
  • 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 Methode tools/list 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 unter Protocol version header in der MCP-Spezifikation.
  • Optional: TOKEN: OAuth 2.0-Zugriffstoken

Die Methode gibt alle Tools zurück, die vom MCP-Endpunkt unterstützt werden. 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 Agenten Ihre MCP-Tools mit Ihrem API-Produkt erkennen.

Monitoring und Analysen

Mit Apigee Analytics können Sie den MCP-Traffic überwachen und Messwerte auf Tool-Ebene 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 versus tools/call Anfragen zu sehen. Weitere Informationen finden Sie unter MCP-Traffic in Apigee überwachen und analysieren.

Nächste Schritte