Premiers pas avec Apigee et MCP

Cette page s'applique à Apigee, mais pas à Apigee hybrid.

Consultez la documentation d' Apigee Edge.

Cette page explique comment utiliser le proxy Apigee Discovery pour rendre vos API disponibles pour les clients MCP (Model Context Protocol) dans les applications agentiques en tant qu'outils MCP.

Avant de commencer

Avant de commencer, effectuez les tâches suivantes :

  1. Connectez-vous à votre compte Google Cloud . Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.

  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. Vérifiez que vous disposez d'une organisation Apigee provisionnée. Le proxy MCP Discovery est disponible pour les organisations par abonnement, en paiement à l'usage et d'évaluation. Pour en savoir plus, consultez Présentation du provisionnement.
  7. Vérifiez qu'une instance de hub d'API Apigee est provisionnée dans votre projet Google Cloud . Pour en savoir plus, consultez Provisionner API Hub dans la console Google Cloud . Vous pouvez vérifier que le service de hub d'API est activé en consultant la page Hub de la console Google Cloud .

    Accéder à l'API Hub

  8. Vérifiez qu'une instance Apigee est associée à votre service de hub d'API. Le proxy MCP Discovery n'est pas compatible avec les instances de plug-in Apigee Edge pour le cloud public ou Apigee Edge pour le cloud privé dans le hub d'API. Pour en savoir plus, consultez Associer un projet d'exécution. Vous pouvez vérifier l'état de l'association du projet d'exécution dans l'onglet Associations de projets de la page Paramètres de la console Google Cloud .

    Accéder à l'API Hub

Rôles requis

Pour obtenir les autorisations nécessaires pour créer et déployer un proxy de découverte MCP, demandez à votre administrateur de vous accorder le rôle IAM Administrateur Apigee (roles/apigee.admin) sur le compte de service que vous utilisez pour déployer des proxys Apigee. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Activer les API

Activez l'API Apigee.

Rôles requis pour activer les API

Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.

Activer l'API

Définir des variables d'environnement

Dans le projet Google Cloud qui contient votre instance Apigee, utilisez la commande suivante pour définir les variables d'environnement : 

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

Où :

  • PROJECT_ID est l'ID du projet contenant votre instance Apigee.
  • REGION est la région Google Cloud de votre instance Apigee.
  • RUNTIME_HOSTNAME est le nom d'hôte de votre environnement d'exécution Apigee.

Pour vérifier que les variables d'environnement sont correctement définies, exécutez la commande suivante et examinez le résultat : 

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

Définir le projet

Définissez le projet Google Cloud dans votre environnement de développement : 

    gcloud auth login
    gcloud config set project $PROJECT_ID

Présentation

Pour exposer vos API en tant qu'outils MCP à l'aide d'Apigee, vous devez créer et déployer un proxy Apigee à l'aide du modèle Proxy de découverte MCP. Une fois votre proxy déployé, vous pouvez créer un produit d'API pour regrouper les opérations de l'API MCP dans votre proxy. En tant que produit d'API, vos opérations/outils d'API sont détectables par les clients MCP grâce à l'intégration dans le hub d'API.

Les sections suivantes décrivent les étapes à suivre pour créer et déployer un proxy de découverte MCP, créer un produit d'API et lister les outils disponibles :

  1. Créez une spécification OpenAPI 3.0.x décrivant les opérations de votre API.
  2. Créez un proxy de découverte MCP.
  3. (Facultatif) Ajoutez une stratégie de sécurité au proxy de découverte MCP.
  4. Déployez le proxy de découverte MCP.
  5. (Facultatif) Initialisez votre serveur MCP.
  6. Liste les outils disponibles.

Créez une spécification OpenAPI 3.0.x décrivant les opérations de votre API.

Avant de créer et de déployer votre proxy de découverte MCP, vous devez créer une spécification OpenAPI 3.0.x qui décrit les opérations d'API que vous souhaitez exposer en tant qu'outils MCP. MCP dans Apigee est compatible avec les versions OpenAPI suivantes :

  • 3.0.0
  • 3.0.1
  • 3.0.2
  • 3.0.3

Ce guide de démarrage rapide utilise un exemple de spécification OpenAPI 3.0.x avec trois opérations d'API :

  • GET /artists : renvoie une liste d'artistes.
  • POST /artists : permet à un utilisateur de publier un nouvel artiste.
  • GET /artists/{username} : obtenez des informations sur un artiste à partir de son nom d'utilisateur unique.

Pour créer la spécification OpenAPI 3.0.x, procédez comme suit :

  1. Créez un fichier mcp-quickstart-openapi.yaml dans le répertoire oas de votre groupe de proxys d'API.
  2. Ajoutez le contenu suivant au fichier  : 
    # 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

Exigence de mise en correspondance du nom d'hôte

Il est essentiel que la valeur du nom d'hôte dans le champ servers.url de la spécification OpenAPI corresponde exactement au nom d'hôte du groupe d'environnement de l'environnement Apigee dans lequel le proxy MCP Discovery est déployé. Cette correspondance est nécessaire pour que les appels tools/list et tools/call fonctionnent correctement.

Le tableau suivant présente la configuration du nom d'hôte dans la spécification OpenAPI et la configuration correspondante du nom d'hôte dans le groupe d'environnements Apigee :

Composant Configuration requise Exemple de valeur Informations complémentaires
Groupe d'environnements Apigee Les noms d'hôte doivent être configurés dans le groupe d'environnements. cymbal.products.com, internal.products.com Les groupes d'environnements permettent d'acheminer le trafic vers un groupe d'environnements à l'aide d'un nom d'hôte.
Spécification OpenAPI La valeur du champ servers.url de la spécification OpenAPI doit correspondre exactement au nom d'hôte du groupe d'environnement de l'environnement Apigee dans lequel le proxy de découverte MCP est déployé. https://cymbal.products.com Si le nom d'hôte servers.url ne correspond pas à celui du groupe d'environnements correspondant à l'environnement Apigee dans lequel le proxy de découverte MCP est déployé, une erreur s'affichera lors du déploiement du proxy.

Créer un proxy de découverte MCP

Maintenant que vous disposez d'une spécification OpenAPI 3.0.x définissant vos opérations d'API, vous pouvez créer un proxy d'API à l'aide du modèle de proxy de découverte MCP.

Pour créer un proxy de découverte MCP :

  1. Accédez à la page Proxys d'API dans la console Google Cloud .

    Accéder aux proxys d'API

  2. Cliquez sur + Créer pour ouvrir le volet Créer un proxy d'API.
  3. Dans la zone Modèle de proxy, sélectionnez Proxy de découverte MCP.
  4. Dans la section Détails du proxy, saisissez les informations suivantes :
    • Nom du proxy : nom de votre proxy.
    • Description (facultatif) : description de votre proxy. Exemple :My first MCP Discovery Proxy
  5. Cliquez sur Suivant.
  6. Dans la section Spécifications OpenAPI, utilisez l'explorateur de fichiers pour sélectionner le fichier OpenAPI 3.0.x que vous avez créé à l'étape précédente.
  7. Cliquez sur Suivant.
  8. Dans la section Déployer (facultatif), vous pouvez ignorer le déploiement de votre proxy pour le moment. Cliquez sur Suivant.
  9. Cliquez sur Créer.

Vous pouvez afficher les points de terminaison cible et de serveur du proxy en cliquant sur Afficher dans la colonne Récapitulatif des points de terminaison du tableau Révisions. Le récapitulatif des points de terminaison de la révision pour la révision du proxy que vous sélectionnez affiche les informations suivantes :

  • Points de terminaison du proxy : dans cet exemple, le point de terminaison du proxy default avec un chemin de base /mcp s'affiche. Si d'autres noms d'hôte ou groupes d'environnements sont ajoutés au proxy, ils s'afficheront également ici.
  • Points de terminaison cibles : dans cet exemple, la connexion cible default est définie sur ORG_NAME.mcp.apigee.internal, où ORG_NAME est le nom de votre organisation Apigee. La cible mcp.apigee.internal est également compatible avec les versions antérieures.

(Facultatif) Ajouter une stratégie de sécurité au proxy de découverte MCP

Avant de déployer votre proxy de découverte MCP, vous pouvez ajouter des règles de sécurité pour appliquer les exigences de sécurité. Nous vous recommandons de sécuriser l'accès à votre proxy MCP Discovery à l'aide de jetons OAuth ou d'une clé API.

Cette section explique comment ajouter une règle OAuthV2 au proxy de découverte MCP. Cela garantit que toutes les requêtes adressées au proxy de découverte MCP sont authentifiées et autorisées. Si vous préférez utiliser une clé API, consultez Sécuriser une API en exigeant des clés API pour connaître les étapes recommandées.

Pour configurer la validation des jetons, placez une règle OAuthV2 avec l'opération VerifyAccessToken au tout début du flux de proxy d'API (le début du flux préliminaire de point de terminaison proxy). Si elle est placée, les jetons d'accès sont vérifiés avant tout autre traitement. Si un jeton est refusé, Apigee arrête le traitement et renvoie une erreur au client.

Pour ajouter la règle VerifyAccessToken :

  1. Sur la page d'informations du proxy, cliquez sur l'onglet Développer.
  2. Sous Proxy Endpoints (Points de terminaison du proxy), cliquez sur default (par défaut), puis sur PreFlow.

  3. Dans l'éditeur de flux proxy, cliquez sur Ajouter une étape de règle.

    Sélectionnez PreFlow (Flux préliminaire) pour un point de terminaison répertorié sous Points de terminaison proxy.
  4. Dans la boîte de dialogue Ajouter une étape de règle, sélectionnez Créer une règle.
  5. Dans la liste des règles, sous Sécurité, sélectionnez OAuth v2.0.
  6. Si vous le souhaitez, modifiez le nom de la règle et le nom à afficher. Par exemple, pour améliorer la lisibilité, vous pouvez à la fois remplacer le nom à afficher et le nom par VerifyAccessToken.
  7. Cliquez sur Ajouter.

Déployer le proxy de découverte MCP

Pour déployer le proxy de découverte MCP :

  1. Cliquez sur Déployer pour ouvrir le volet Déployer le proxy d'API.
  2. Le champ Révision doit être défini sur 1. Si ce n'est pas le cas, cliquez sur 1 pour la sélectionner.
  3. Dans la liste Environnement, sélectionnez l'environnement dans lequel vous souhaitez déployer le proxy. L'environnement doit être un environnement complet.
  4. Saisissez le compte de service que vous avez créé lors d'une étape précédente.
  5. Cliquez sur Déployer.

Lorsque vous cliquez sur Déployer, Apigee commence à déployer le proxy et à provisionner les composants en aval. Pendant ce temps, qui peut prendre plusieurs minutes, l'UI affiche l'état Provisionnement pour le déploiement.

Une fois le processus terminé, l'état passe à Déployé et le proxy est prêt à gérer le trafic.

Une fois le proxy déployé, vérifiez que la valeur du nom d'hôte dans le champ servers.url de la spécification OpenAPI correspond exactement au nom d'hôte du groupe d'environnement de l'environnement Apigee dans lequel le proxy MCP Discovery est déployé.

Découvrir les outils MCP dans le hub d'API

Une fois votre proxy de découverte MCP déployé, ses opérations d'API sont automatiquement ingérées dans le hub d'API et rendues détectables en tant qu'outils MCP.

Pour afficher vos outils MCP dans le hub d'API :

  1. Dans la console Google Cloud , accédez à la page API Hub > API.

    Accéder à la page API du hub d'API

  2. Cliquez sur Filtrer, puis sélectionnez Style > MCP, puis cliquez sur Appliquer.
  3. Votre proxy MCP déployé doit apparaître dans la liste. Le pipeline d'ingestion du hub d'API mappe automatiquement les chemins d'accès définis dans votre spécification OpenAPI aux outils MCP individuels listés dans le hub.

Les développeurs de votre organisation peuvent désormais utiliser des filtres ou la recherche sémantique dans le hub d'API pour trouver les outils MCP pertinents à l'aide de requêtes en langage naturel.

Initialiser votre serveur MCP

Au cours de cette étape, vous allez envoyer une requête à votre point de terminaison MCP pour initialiser votre serveur MCP et vérifier qu'il fonctionne comme prévu.

Pour initialiser et tester votre serveur MCP, envoyez la requête suivante à votre point de terminaison MCP : 

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"

Remplacez les éléments suivants :

  • MCP_ENDPOINT_URL : URI de base de votre point de terminaison MCP. Exemple :cymbal.products.com
  • MCP_PROTOCOL_VERSION : version du protocole MCP. Exemple :2025-11-25 Pour en savoir plus, consultez la section Négociation de version dans les spécifications MCP.
  • (Facultatif) TOKEN : jeton d'accès OAuth 2.0

Une réponse réussie ressemble à ceci :

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

Lister les outils MCP disponibles

Dans cette étape, vous envoyez une requête à la méthode tools/list pour confirmer la liste des outils disponibles dans votre point de terminaison MCP.

Envoyez une requête à la méthode tools/list pour votre proxy Apigee :

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"

Remplacez les éléments suivants :

  • MCP_ENDPOINT_URL : URI de base de votre point de terminaison MCP. Exemple :cymbal.products.com
  • MCP_PROTOCOL_VERSION : version du protocole MCP. Exemple :2025-11-25 Pour en savoir plus, consultez la section En-tête de version du protocole dans les spécifications MCP.
  • (Facultatif) TOKEN : jeton d'accès OAuth 2.0

La méthode renvoie tous les outils compatibles avec le point de terminaison MCP. Une réponse réussie ressemble à ceci :

{
  "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"
      }
    ]
  }
}

Maintenant que votre point de terminaison est initialisé, les développeurs et les agents peuvent découvrir vos outils MCP à l'aide de votre produit d'API.

Surveillance et analyse

Vous pouvez surveiller le trafic MCP et afficher les métriques au niveau de l'outil à l'aide d'Apigee Analytics. Apigee Analytics vous permet de filtrer les métriques pour faire la distinction entre le trafic d'API standard et le trafic spécifique à MCP, et d'afficher le volume d'utilisation pour les requêtes tools/list par rapport aux requêtes tools/call. Pour en savoir plus, consultez Surveiller et analyser le trafic MCP dans Apigee.

Étapes suivantes