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 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 mit Google Cloudnoch nicht vertraut sind, erstellen Sie 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 Sie eine Apigee-Organisation eingerichtet haben. Der MCP Discovery-Proxy ist für Abo-, Pay-as-you-go- und Evaluierungsorganisationen sowie für Apigee Hybrid Version 1.17.0 und höher verfügbar. Weitere Informationen finden Sie unter Einführung in die Bereitstellung.
  7. Nur Apigee Hybrid:Prüfen Sie, ob Sie die einmaligen Schritte zur Clusteraktivierung ausgeführt haben, die unter MCP in Apigee Hybrid aktivieren beschrieben sind. Dazu müssen Sie enableMcpServer: true als Schlüssel der obersten Ebene in Ihrem overrides.yaml festlegen und helm upgrade für die Diagramme apigee-operator und apigee-org ausführen.
  8. Prüfen Sie, ob in Ihrem Google Cloud Projekt eine Apigee API-Hub-Instanz bereitgestellt ist. Weitere Informationen finden Sie unter API Hub in der Google Cloud -Konsole 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

  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 öffentliche Cloud- oder Apigee Edge for private Cloud-Plug-in-Instanzen im API-Hub unterstützt. Weitere Informationen finden Sie unter Laufzeitprojekt anhängen. Den Status der Anhängung des Laufzeitprojekts können Sie 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 die IAM-Rolle Apigee Admin (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.

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, das Ihre Apigee-Instanz enthält, 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. 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 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 bereitstellen 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 bündeln. Als API-Produkt sind Ihre API-Vorgänge/-Tools für MCP-Kunden durch die Integration in den API-Hub auffindbar.

In den folgenden Abschnitten wird beschrieben, wie Sie einen MCP Discovery-Proxy erstellen und bereitstellen, ein API-Produkt erstellen und verfügbare Tools auflisten:

  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. MCP-Discovery-Proxy bereitstellen
  5. Optional: Initialisieren Sie Ihren MCP-Server.
  6. Verfügbare Tools auflisten

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 Beispiel-OpenAPI 3.0.x-Spezifikation 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}: Informationen zu einem Künstler anhand seines eindeutigen Nutzernamens abrufen.

So erstellen Sie die OpenAPI 3.0.x-Spezifikation:

  1. Erstellen Sie eine neue Datei mcp-quickstart-openapi.yaml 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 den Hostnamenabgleich

Der Wert des Hostnamens im Feld servers.url der OpenAPI-Spezifikation muss exakt mit dem Hostname der Umgebungsgruppe der Apigee-Umgebung übereinstimmen, in der der MCP Discovery-Proxy bereitgestellt wird. Dieser Abgleich ist erforderlich, damit die Aufrufe von 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 Informationen
Apigee-Umgebungsgruppe Hostnamen müssen in der Umgebungsgruppe konfiguriert werden. cymbal.products.com, internal.products.com Mit Umgebungsgruppen können Sie das Routing zu einer Gruppe von Umgebungen über einen Hostnamen ermöglichen.
OpenAPI-Spezifikation Der Wert des Felds servers.url der OpenAPI-Spezifikation muss genau mit dem Hostname 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 eine Fehlermeldung.

MCP-Discovery-Proxy erstellen

Nachdem Sie eine OpenAPI 3.0.x-Spezifikation 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 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 der Dateiauswahl 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 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 Spalte Endpunktzusammenfassung der Tabelle Revisionen auf Anzeigen klicken. Die Zusammenfassung des Revisionsendpunkts für die ausgewählte Proxy-Revision enthält die folgenden Informationen:

  • 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 zur Abwärtskompatibilität unterstützt.

Optional: Sicherheitsrichtlinie für den MCP-Discovery-Proxy hinzufügen

Bevor Sie Ihren MCP Discovery-Proxy bereitstellen, können Sie Sicherheitsrichtlinien hinzufügen, um Sicherheitsanforderungen zu erzwingen. 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.

Um die Tokenüberprüfung zu konfigurieren, platzieren Sie eine OAuthV2-Richtlinie mit dem Vorgang VerifyAccessToken ganz am Anfang des API-Proxy-Ablaufs (am Anfang des ProxyEndpoint Preflow). Wenn sie dort platziert werden, werden Zugriffstokens vor jeder anderen Verarbeitung überprüft. 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 Proxyablaufeditor 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 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 Revision sollte auf 1 gesetzt 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 Comprehensive-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 einige Minuten dauern kann, wird in der Benutzeroberfläche der Status Bereitstellung für das Deployment 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 Hostname der Umgebungsgruppe der Apigee-Umgebung übereinstimmt, in der der MCP Discovery Proxy bereitgestellt wird.

MCP-Tools im API-Hub entdecken

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

  2. Klicken Sie auf Filtern und wählen Sie Stil > MCP aus. Klicken Sie dann auf Übernehmen.
  3. Ihr bereitgestellter MCP-Proxy sollte in der Liste angezeigt werden. In der API Hub-Aufnahmepipeline werden die in Ihrer OpenAPI-Spezifikation definierten Pfade automatisch den einzelnen MCP-Tools zugeordnet, 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 Anfragen 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 Version Negotiation.
  • (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 in der MCP-Spezifikation unter Protocol version header.
  • (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, die Ihr API-Produkt verwenden, Ihre MCP-Tools erkennen.

Monitoring und Analysen

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

Nächste Schritte