Comienza a usar Apigee y MCP

Esta página se aplica a Apigee, pero no a Apigee Hybrid.

Consulta la documentación de Apigee Edge.

En esta página, se describe cómo usar el proxy de descubrimiento de Apigee para que tus APIs estén disponibles para los clientes del Protocolo de contexto del modelo (MCP) en aplicaciones de agentes como herramientas de MCP.

Antes de comenzar

Antes de comenzar, completa las siguientes tareas:

  1. Accede a tu Google Cloud cuenta de. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

  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. Confirma que tienes una organización de Apigee aprovisionada. El proxy de descubrimiento de MCP está disponible para organizaciones de suscripción, de pago por uso y de evaluación. Para obtener más información, consulta Introducción al aprovisionamiento.
  7. Confirma que tienes una instancia del centro de APIs de Apigee aprovisionada en tu proyecto de Google Cloud . Para obtener más información, consulta Aprovisiona el centro de APIs en la Google Cloud consola. Puedes confirmar que el servicio del centro de APIs está habilitado si verificas la página Centro en la Google Cloud consola de.

    Ir al centro de APIs

  8. Confirma que una instancia de Apigee esté adjunta a tu servicio del centro de APIs. El proxy de descubrimiento de MCP no es compatible con el uso de instancias de complementos de Apigee Edge para la nube pública o Apigee Edge para la nube privada en el centro de APIs. Para obtener más información, consulta Adjunta un proyecto de entorno de ejecución. Puedes verificar el estado de la adjunción del proyecto de entorno de ejecución en la pestaña Asociaciones de proyectos de la página Configuración en la Google Cloud consola de.

    Ir al centro de APIs

Roles obligatorios

Para obtener los permisos que necesitas para crear e implementar un proxy de descubrimiento de MCP, pídele a tu administrador que te otorgue el rol de IAM de administrador de Apigee (roles/apigee.admin) en la cuenta de servicio que usas para implementar proxies de Apigee. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Habilita las APIs

Habilita la API de Apigee.

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

Habilitar la API

Configura las variables de entorno

En el Google Cloud proyecto de que contiene tu instancia de Apigee, usa el siguiente comando para configurar las variables de entorno: 

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

Aquí:

  • PROJECT_ID es el ID del proyecto con tu instancia de Apigee.
  • REGION es la Google Cloud región de tu instancia de Apigee.
  • RUNTIME_HOSTNAME es el nombre de host de tu entorno de ejecución de Apigee.

Para confirmar que las variables de entorno estén configuradas correctamente, ejecuta el siguiente comando y revisa el resultado: 

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

Configura el proyecto

Configura el Google Cloud proyecto de en tu entorno de desarrollo: 

    gcloud auth login
    gcloud config set project $PROJECT_ID

Descripción general

Para exponer tus APIs como herramientas de MCP con Apigee, crea e implementa un nuevo proxy de Apigee con la plantilla Proxy de descubrimiento de MCP. Después de que se implemente el proxy, puedes crear un producto de API para agrupar las operaciones de la API de MCP en tu proxy en un producto de API. Como producto de API, los clientes de MCP pueden descubrir tus operaciones o herramientas de API a través de la integración en el centro de APIs.

En las siguientes secciones, se describen los pasos para crear e implementar un proxy de descubrimiento de MCP, crear un producto de API y enumerar las herramientas disponibles:

  1. Crea una especificación de OpenAPI 3.0.x que describa tus operaciones de API.
  2. Crea un proxy de descubrimiento de MCP.
  3. (Opcional) Agrega una política de seguridad al proxy de descubrimiento de MCP.
  4. Implementa el proxy de descubrimiento de MCP.
  5. (Opcional) Inicializa tu servidor de MCP.
  6. Enumera las herramientas disponibles.

Crea una especificación de OpenAPI 3.0.x que describa tus operaciones de API

Antes de crear e implementar tu proxy de descubrimiento de MCP, debes crear una especificación de OpenAPI 3.0.x que describa las operaciones de API que deseas exponer como herramientas de MCP. MCP en Apigee admite las siguientes versiones de OpenAPI:

  • 3.0.0
  • 3.0.1
  • 3.0.2
  • 3.0.3

En esta guía de inicio rápido, se usa una especificación de OpenAPI 3.0.x de muestra con tres operaciones de API:

  • GET /artists: Muestra una lista de artistas.
  • POST /artists: Permite que un usuario publique un artista nuevo.
  • GET /artists/{username}: Obtén información sobre un artista a partir de su nombre de usuario único.

Para crear la especificación de OpenAPI 3.0.x, haz lo siguiente:

  1. Crea un archivo mcp-quickstart-openapi.yaml nuevo en el directorio oas de tu paquete de proxy de API.
  2. Agrega el siguiente contenido al archivo: 
    # 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 de coincidencia de nombre de host

Es fundamental que el valor del nombre de host en el campo servers.url de la especificación de OpenAPI coincida exactamente con el nombre de host del grupo de entornos del entorno de Apigee en el que se implementa el proxy de descubrimiento de MCP. Esta coincidencia es necesaria para que las llamadas tools/list y tools/call funcionen correctamente.

En la siguiente tabla, se muestra la configuración del nombre de host en la especificación de OpenAPI y la configuración del nombre de host correspondiente en el grupo de entornos de Apigee:

Componente Configuración obligatoria Valor de ejemplo Información adicional
Grupo de entornos de Apigee Los nombres de host deben configurarse en el grupo de entornos. cymbal.products.com, internal.products.com Los grupos de entornos permiten el enrutamiento a un grupo de entornos con un nombre de host.
Especificación de OpenAPI El valor del campo servers.url de la especificación de OpenAPI debe coincidir exactamente con el nombre de host del grupo de entornos del entorno de Apigee en el que se implementa el proxy de descubrimiento de MCP. https://cymbal.products.com Si el nombre de host servers.url no coincide con el nombre de host del grupo de entornos correspondiente al entorno de Apigee en el que se implementa el proxy de descubrimiento de MCP, recibirás un error cuando implementes el proxy.

Crea un proxy de descubrimiento de MCP

Ahora que tienes una especificación de OpenAPI 3.0.x que define tus operaciones de API, puedes crear un proxy de API nuevo con la plantilla Proxy de descubrimiento de MCP.

Para crear un proxy de descubrimiento de MCP, haz lo siguiente:

  1. Ve a la página Proxies de API en la Google Cloud consola de.

    Ir a los proxies de API

  2. Haz clic en + Crear para abrir el panel Crear proxy de API.
  3. En el cuadro Plantilla de proxy, selecciona Proxy de descubrimiento de MCP.
  4. En la sección Detalles del proxy, ingresa los siguientes detalles:
    • Nombre del proxy: Un nombre para tu proxy.
    • Descripción (opcional): Una descripción para tu proxy. Por ejemplo, My first MCP Discovery Proxy.
  5. Haz clic en Siguiente.
  6. En la sección Especificaciones de OpenAPI, usa el navegador de archivos para seleccionar el archivo de OpenAPI 3.0.x que creaste en el paso anterior.
  7. Haz clic en Siguiente.
  8. En la sección Implementar (opcional), puedes omitir la implementación de tu proxy por ahora. Haz clic en Siguiente.
  9. Haz clic en Crear.

Para ver los extremos de destino y del servidor del proxy, haz clic en Ver en la columna Resumen del extremo de la tabla Revisiones. El Resumen del extremo de revisión para la revisión del proxy que selecciones muestra la siguiente información:

  • Extremos de proxy: En este ejemplo, se muestra el extremo de proxy default con una ruta base de /mcp. Si se agregan nombres de host o grupos de entornos adicionales al proxy, también se mostrarán aquí.
  • Extremos de destino: En este ejemplo, la conexión de destino default se establece en ORG_NAME.mcp.apigee.internal, donde ORG_NAME es el nombre de tu organización de Apigee. El destino mcp.apigee.internal también es compatible con versiones anteriores.

(Opcional) Agrega una política de seguridad al proxy de descubrimiento de MCP

Antes de implementar tu proxy de descubrimiento de MCP, puedes agregar políticas de seguridad para aplicar requisitos de seguridad. Te recomendamos que protejas el acceso a tu proxy de descubrimiento de MCP con tokens de OAuth o una clave de API.

En esta sección, se describe cómo agregar una política de OAuthV2 al proxy de descubrimiento de MCP. Esto garantiza que todas las solicitudes al proxy de descubrimiento de MCP se autentiquen y autoricen. Si deseas usar una clave de API, consulta Protege una API con la exigencia de claves de API para conocer los pasos recomendados.

Para configurar la verificación del token, coloca una política de OAuthV2 con la operación VerifyAccessToken al comienzo del flujo del proxy de API (el comienzo del flujo de preprocesamiento de ProxyEndpoint). Si se coloca allí, los tokens de acceso se verifican antes de que se realice cualquier otro procesamiento, y si se rechaza un token, Apigee deja de procesarlo y muestra un error al cliente.

Para agregar la política de VerifyAccessToken, haz lo siguiente:

  1. En la página de detalles del proxy, haz clic en la pestaña Desarrollar.
  2. En Extremos de proxy, haz clic en predeterminado y, luego, en PreFlow.

  3. En el editor de flujo de proxy, haz clic en Agregar paso de la política.

    Selecciona PreFlow para un extremo que se encuentra en Proxy Endpoints.
  4. En el cuadro de diálogo Agregar paso de la política, selecciona Crear una política nueva.
  5. En la lista de políticas, en Seguridad, selecciona OAuth v2.0.
  6. Opcionalmente, cambia el nombre de la política y el nombre visible. Por ejemplo, para mejorar la legibilidad, puedes cambiar el Nombre visible y el Nombre a VerifyAccessToken.
  7. Haz clic en Agregar.

Implementa el proxy de descubrimiento de MCP

Para implementar el proxy de descubrimiento de MCP, haz lo siguiente:

  1. Haz clic en Implementar para abrir el panel Implementar proxy de API.
  2. El campo Revisión debe establecerse en 1. De lo contrario, haz clic en 1 para seleccionarlo.
  3. En la lista Entorno, selecciona el entorno en el que deseas implementar el proxy. El entorno debe ser un entorno integral.
  4. Ingresa la Cuenta de servicio que creaste en un paso anterior.
  5. Haz clic en Implementar.

Cuando haces clic en Implementar, Apigee comienza a implementar el proxy y a aprovisionar los componentes descendentes. Durante este tiempo, que puede tardar varios minutos, la IU mostrará un estado de Aprovisionamiento para la implementación.

Cuando se complete el proceso, el estado cambiará a Implementado y el proxy estará listo para controlar el tráfico.

Después de que se implemente el proxy, confirma que el valor del nombre de host en el campo servers.url de la especificación de OpenAPI coincida exactamente con el nombre de host del grupo de entornos del entorno de Apigee en el que se implementa el proxy de descubrimiento de MCP.

Descubre herramientas de MCP en el centro de APIs

Una vez que se implementa tu proxy de descubrimiento de MCP, sus operaciones de API se incorporan automáticamente al centro de APIs y se pueden descubrir como herramientas de MCP.

Para ver tus herramientas de MCP en el centro de APIs, haz lo siguiente:

  1. En la Google Cloud consola, ve a la página Centro de APIs > APIs.

    Ir a APIs del centro de APIs

  2. Haz clic en Filtrar y selecciona Estilo > MCP y, luego, haz clic en Aplicar.
  3. Tu proxy de MCP implementado debería aparecer en la lista. La canalización de incorporación del centro de APIs asigna automáticamente las rutas definidas en tu especificación de OpenAPI a herramientas de MCP individuales que se muestran en el centro.

Los desarrolladores de tu organización ahora pueden usar filtros o la búsqueda semántica en el centro de APIs para encontrar herramientas de MCP relevantes con consultas en lenguaje natural.

Inicializa tu servidor de MCP

En este paso, envías una solicitud a tu extremo de MCP para inicializar tu servidor de MCP y confirmar que funciona como se espera.

Para inicializar y probar tu servidor de MCP, envía la siguiente solicitud a tu extremo de 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"

Reemplaza lo siguiente:

  • MCP_ENDPOINT_URL: Es el URI base de tu extremo de MCP. Por ejemplo, cymbal.products.com.
  • MCP_PROTOCOL_VERSION: Es la versión del protocolo de MCP. Por ejemplo, 2025-11-25. Consulta Negociación de versiones en la especificación de MCP para obtener más información.
  • (Opcional) TOKEN: Token de acceso de OAuth 2.0

Una respuesta correcta es similar a la siguiente:

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

Enumera las herramientas de MCP disponibles

En este paso, envías una solicitud al método tools/list para confirmar la lista de herramientas disponibles en tu extremo de MCP.

Envía una solicitud al método tools/list para tu proxy de 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"

Reemplaza lo siguiente:

  • MCP_ENDPOINT_URL: Es el URI base de tu extremo de MCP. Por ejemplo, cymbal.products.com.
  • MCP_PROTOCOL_VERSION: Es la versión del protocolo de MCP. Por ejemplo, 2025-11-25. Consulta Encabezado de versión del protocolo en la especificación de MCP para obtener más información.
  • (Opcional) TOKEN: Token de acceso de OAuth 2.0

El método muestra todas las herramientas que admite el extremo de MCP. Una respuesta correcta es similar a la siguiente:

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

Ahora que tu extremo está inicializado, los desarrolladores y agentes pueden descubrir tus herramientas de MCP con tu producto de API.

Supervisión y estadísticas

Puedes supervisar el tráfico de MCP y ver las métricas a nivel de la herramienta con Apigee Analytics. Apigee Analytics te permite filtrar métricas para distinguir entre el tráfico de API estándar y el tráfico específico de MCP, y para ver el volumen de uso de las solicitudes tools/list en comparación con las solicitudes tools/call. Para obtener más información, consulta Supervisa y analiza el tráfico de MCP en Apigee.

¿Qué sigue?