Inizia a utilizzare Apigee e MCP

Questa pagina si applica ad Apigee, ma non ad Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questa pagina descrive come utilizzare il proxy Apigee Discovery per rendere le tue API disponibili per i client Model Context Protocol (MCP) nelle applicazioni agentiche come strumenti MCP.

Prima di iniziare

Prima di iniziare, completa le seguenti attività:

  1. Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

  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. Verifica di aver eseguito il provisioning di un'organizzazione Apigee. Il proxy MCP Discovery è disponibile per le organizzazioni con abbonamento, pagamento a consumo e valutazione. Per saperne di più, consulta Introduzione al provisioning.
  7. Verifica di aver eseguito il provisioning di un'istanza dell'hub delle API Apigee nel tuo progetto Google Cloud . Per saperne di più, vedi Esegui il provisioning dell'hub API nella console Google Cloud . Puoi verificare che il servizio hub API sia abilitato controllando la pagina Hub nella console Google Cloud .

    Vai all'hub API

  8. Verifica che un'istanza Apigee sia collegata al servizio hub API. Il proxy di rilevamento MCP non è supportato per l'utilizzo con le istanze del plug-in Apigee Edge per il cloud pubblico o Apigee Edge per il cloud privato in API Hub. Per saperne di più, consulta Allegare un progetto di runtime. Puoi controllare lo stato dell'allegato del progetto di runtime nella scheda Associazioni progetto della pagina Impostazioni nella console Google Cloud .

    Vai all'hub API

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare e deployment di un proxy di rilevamento MCP, chiedi all'amministratore di concederti il ruolo IAM Apigee Admin (roles/apigee.admin) sul account di servizio che utilizzi per il deployment dei proxy Apigee. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Abilita API

Abilita l'API Apigee.

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

Abilitare l'API

Imposta le variabili di ambiente

Nel progetto Google Cloud che contiene l'istanza Apigee, utilizza il seguente comando per impostare le variabili di ambiente: 

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

Dove:

  • PROJECT_ID è l'ID del progetto con la tua istanza Apigee.
  • REGION è la regione Google Cloud dell'istanza Apigee.
  • RUNTIME_HOSTNAME è il nome host del runtime Apigee.

Per verificare che le variabili di ambiente siano impostate correttamente, esegui il comando seguente ed esamina l'output: 

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

Impostare il progetto

Imposta il progetto Google Cloud nell'ambiente di sviluppo: 

    gcloud auth login
    gcloud config set project $PROJECT_ID

Panoramica

Per esporre le tue API come strumenti MCP utilizzando Apigee, crea ed esegui il deployment di un nuovo proxy Apigee utilizzando il modello Proxy di rilevamento MCP. Una volta eseguito il deployment del proxy, puoi creare un prodotto API per raggruppare le operazioni dell'API MCP nel proxy in un prodotto API. In qualità di prodotto API, le tue operazioni/strumenti API sono rilevabili dai client MCP tramite l'integrazione nell'hub API.

Le sezioni seguenti descrivono i passaggi per creare e implementare un proxy di rilevamento MCP, creare un prodotto API ed elencare gli strumenti disponibili:

  1. Crea una specifica OpenAPI 3.0.x che descriva le operazioni API.
  2. Crea un proxy di rilevamento MCP.
  3. (Facoltativo) Aggiungi una policy di sicurezza al proxy di rilevamento MCP.
  4. Esegui il deployment del proxy di rilevamento MCP.
  5. (Facoltativo) Inizializza il server MCP.
  6. Elenca gli strumenti disponibili.

Crea una specifica OpenAPI 3.0.x che descriva le operazioni API

Prima di creare ed eseguire il deployment del proxy di rilevamento MCP, devi creare una specifica OpenAPI 3.0.x che descriva le operazioni API che vuoi esporre come strumenti MCP. MCP in Apigee supporta le seguenti versioni di OpenAPI:

  • 3.0.0
  • 3.0.1
  • 3.0.2
  • 3.0.3

Questa guida rapida utilizza una specifica OpenAPI 3.0.x di esempio con tre operazioni API:

  • GET /artists: restituisce un elenco di artisti.
  • POST /artists: consente a un utente di pubblicare un nuovo artista.
  • GET /artists/{username}: Ottieni informazioni su un artista dal suo nome utente univoco.

Per creare la specifica OpenAPI 3.0.x:

  1. Crea un nuovo file mcp-quickstart-openapi.yaml nella directory oas del bundle del proxy API.
  2. Aggiungi i seguenti contenuti al file: 
    # 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

Requisito di corrispondenza del nome host

È fondamentale che il valore del nome host nel campo servers.url della specifica OpenAPI corrisponda esattamente al nome host del gruppo di ambienti dell'ambiente Apigee in cui è stato eseguito il deployment del proxy di rilevamento MCP. Questa corrispondenza è necessaria per il corretto funzionamento delle chiamate tools/list e tools/call.

La tabella seguente mostra la configurazione del nome host nella specifica OpenAPI e la configurazione del nome host corrispondente nel gruppo di ambienti Apigee:

Componente Configurazione richiesta Valore di esempio Informazioni di supporto
Gruppo di ambienti Apigee I nomi host devono essere configurati nel gruppo di ambienti. cymbal.products.com, internal.products.com I gruppi di ambienti consentono il routing a un gruppo di ambienti utilizzando un nome host.
Specifica OpenAPI Il valore del campo servers.url della specifica OpenAPI deve corrispondere esattamente all'hostname del gruppo di ambienti Apigee in cui viene eseguito il deployment del proxy di rilevamento MCP. https://cymbal.products.com Se il nome host servers.url non corrisponde al nome host del gruppo di ambienti corrispondente all'ambiente Apigee in cui è stato deployment del proxy di rilevamento MCP, viene visualizzato un errore durante il deployment del proxy.

Crea un proxy di rilevamento MCP

Ora che hai una specifica OpenAPI 3.0.x che definisce le operazioni API, puoi creare un nuovo proxy API utilizzando il modello Proxy di rilevamento MCP.

Per creare un proxy di rilevamento MCP:

  1. Vai alla pagina Proxy API nella console Google Cloud .

    Vai ai proxy API

  2. Fai clic su + Crea per aprire il riquadro Crea proxy API.
  3. Nella casella Modello proxy, seleziona Proxy di rilevamento MCP.
  4. Nella sezione Dettagli proxy, inserisci i seguenti dettagli:
    • Nome proxy: un nome per il proxy.
    • (Facoltativo) Descrizione: una descrizione del proxy. Ad esempio, My first MCP Discovery Proxy.
  5. Fai clic su Avanti.
  6. Nella sezione Specifiche OpenAPI, utilizza il browser di file per selezionare il file OpenAPI 3.0.x creato nel passaggio precedente.
  7. Fai clic su Avanti.
  8. Nella sezione Deploy (facoltativo), puoi saltare il deployment del proxy per il momento. Fai clic su Avanti.
  9. Fai clic su Crea.

Puoi visualizzare gli endpoint di destinazione e server del proxy facendo clic su Visualizza nella colonna Riepilogo endpoint della tabella Revisioni. Il Riepilogo endpoint revisione per la revisione del proxy selezionata mostra le seguenti informazioni:

  • Endpoint proxy: in questo esempio, viene visualizzato l'endpoint proxy default con un percorso di base /mcp. Se al proxy vengono aggiunti altri nomi host o gruppi di ambienti, verranno visualizzati anche qui.
  • Endpoint di destinazione: in questo esempio, la connessione di destinazione default è impostata su ORG_NAME.mcp.apigee.internal, dove ORG_NAME è il nome della tua organizzazione Apigee. La destinazione mcp.apigee.internal è supportata anche per la compatibilità con le versioni precedenti.

(Facoltativo) Aggiungi una policy di sicurezza al proxy di rilevamento MCP

Prima di eseguire il deployment del proxy di rilevamento MCP, puoi aggiungere policy di sicurezza per applicare i requisiti di sicurezza. Ti consigliamo di proteggere l'accesso al proxy di rilevamento MCP utilizzando token OAuth o una chiave API.

Questa sezione descrive come aggiungere una policy OAuthV2 al proxy di rilevamento MCP. In questo modo, tutte le richieste al proxy di rilevamento MCP vengono autenticate e autorizzate. Se invece vuoi utilizzare una chiave API, consulta Proteggere un'API richiedendo chiavi API per i passaggi consigliati.

Per configurare la verifica del token, inserisci un criterio OAuthV2 con l'operazione VerifyAccessToken all'inizio del flusso del proxy API (all'inizio del pre-flusso ProxyEndpoint). Se inseriti qui, i token di accesso vengono verificati prima che venga eseguita qualsiasi altra elaborazione e, se un token viene rifiutato, Apigee interrompe l'elaborazione e restituisce un errore al client.

Per aggiungere la policy VerifyAccessToken:

  1. Nella pagina dei dettagli del proxy, fai clic sulla scheda Sviluppa.
  2. In Endpoint proxy, fai clic su default e poi su PreFlow.

  3. Nell'editor del flusso proxy, fai clic su Aggiungi passaggio criterio.

    Seleziona PreFlow per un endpoint elencato in Endpoint proxy.
  4. Nella finestra di dialogo Aggiungi passaggio policy, seleziona Crea nuova policy.
  5. Nell'elenco dei criteri, seleziona OAuth v2.0 nella sezione Sicurezza.
  6. (Facoltativo) Modifica il nome e il nome visualizzato della policy. Ad esempio, per una migliore leggibilità, puoi modificare sia il nome visualizzato che il nome in VerifyAccessToken.
  7. Fai clic su Aggiungi.

Esegui il deployment del proxy di rilevamento MCP

Per eseguire il deployment del proxy di rilevamento MCP:

  1. Fai clic su Esegui il deployment per aprire il riquadro Esegui il deployment del proxy API.
  2. Il campo Revisione deve essere impostato su 1. In caso contrario, fai clic su 1 per selezionarlo.
  3. Nell'elenco Ambiente, seleziona l'ambiente in cui vuoi eseguire il deployment del proxy. L'ambiente deve essere un ambiente completo.
  4. Inserisci il service account che hai creato in un passaggio precedente.
  5. Fai clic su Esegui il deployment.

Quando fai clic su Esegui il deployment, Apigee inizia a eseguire il deployment del proxy e il provisioning dei componenti downstream. Durante questo periodo, che potrebbe richiedere diversi minuti, l'interfaccia utente mostrerà lo stato Provisioning per il deployment.

Al termine del processo, lo stato cambia in Eseguito il deployment e il proxy è pronto a gestire il traffico.

Dopo il deployment del proxy, verifica che il valore del nome host nel campo servers.url della specifica OpenAPI corrisponda esattamente al nome host del gruppo di ambienti dell'ambiente Apigee in cui è stato eseguito il deployment del proxy di rilevamento MCP.

Scopri gli strumenti MCP nell'hub API

Una volta eseguito il deployment del proxy di rilevamento MCP, le relative operazioni API vengono automaticamente inserite nell'hub API e rese rilevabili come strumenti MCP.

Per visualizzare gli strumenti MCP nell'hub API:

  1. Nella console Google Cloud , vai alla pagina Hub API > API.

    Vai alle API dell'hub API

  2. Fai clic su Filtro e seleziona Stile > MCP, poi fai clic su Applica.
  3. Il proxy MCP di cui è stato eseguito il deployment dovrebbe essere visualizzato nell'elenco. La pipeline di importazione dell'hub API mappa automaticamente i percorsi definiti nella specifica OpenAPI ai singoli strumenti MCP elencati nell'hub.

Gli sviluppatori della tua organizzazione ora possono utilizzare i filtri o la ricerca semantica nell'hub API per trovare strumenti MCP pertinenti utilizzando query in linguaggio naturale.

Inizializza il server MCP

In questo passaggio, invii una richiesta all'endpoint MCP per inizializzare il server MCP e verificare che funzioni come previsto.

Per inizializzare e testare il server MCP, invia la seguente richiesta all'endpoint 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"

Sostituisci quanto segue:

  • MCP_ENDPOINT_URL: l'URI di base dell'endpoint MCP. Ad esempio, cymbal.products.com.
  • MCP_PROTOCOL_VERSION: la versione del protocollo MCP. Ad esempio, 2025-11-25. Per ulteriori informazioni, consulta la sezione Negoziazione della versione nella specifica MCP.
  • (Facoltativo) TOKEN: token di accesso OAuth 2.0

Una risposta corretta è simile alla seguente:

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

Elenca gli strumenti MCP disponibili

In questo passaggio, invii una richiesta al metodo tools/list per confermare l'elenco degli strumenti disponibili nell'endpoint MCP.

Invia una richiesta al metodo tools/list per il 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"

Sostituisci quanto segue:

  • MCP_ENDPOINT_URL: l'URI di base dell'endpoint MCP. Ad esempio, cymbal.products.com.
  • MCP_PROTOCOL_VERSION: la versione del protocollo MCP. Ad esempio, 2025-11-25. Per ulteriori informazioni, consulta la sezione Intestazione della versione del protocollo nella specifica MCP.
  • (Facoltativo) TOKEN: token di accesso OAuth 2.0

Il metodo restituisce tutti gli strumenti supportati dall'endpoint MCP. Una risposta corretta è simile alla seguente:

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

Ora che l'endpoint è inizializzato, gli strumenti MCP sono rilevabili da sviluppatori e agenti che utilizzano il tuo prodotto API.

Monitoraggio e analisi

Puoi monitorare il traffico MCP e visualizzare le metriche a livello di strumento utilizzando Apigee Analytics. Apigee Analytics ti consente di filtrare le metriche per distinguere tra il traffico API standard e il traffico specifico di MCP e di visualizzare il volume di utilizzo per le richieste tools/list rispetto a quelle tools/call. Per saperne di più, consulta Monitorare e analizzare il traffico MCP in Apigee.

Passaggi successivi