Comienza a usar Apigee y MCP

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

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

Antes de comenzar

Antes de comenzar, completa las siguientes tareas:

  1. Accede a tu cuenta de Google Cloud . 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 aprovisionada una organización de Apigee. El proxy de detección de MCP está disponible para las organizaciones de suscripción, pago por uso y evaluación, y para la versión 1.17.0 y posteriores de Apigee Hybrid. Para obtener más información, consulta Introducción al aprovisionamiento.
  7. Solo para Apigee Hybrid: Confirma que completaste los pasos de habilitación del clúster únicos que se describen en Habilita MCP en Apigee Hybrid. Esto implica establecer enableMcpServer: true como una clave de nivel superior en tu overrides.yaml y ejecutar helm upgrade en los gráficos de apigee-operator y apigee-org.
  8. 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 Provision API hub in the Google Cloud console. Para confirmar que el servicio del centro de APIs está habilitado, consulta la página Hub en la consola de Google Cloud .

    Ir al centro de APIs

  9. Confirma que una instancia de Apigee esté adjunta a tu servicio de API hub. El proxy de MCP Discovery no es compatible con el uso de instancias del complemento de Apigee Edge para la nube pública o Apigee Edge para la nube privada en el concentrador de APIs. Para obtener más información, consulta Cómo adjuntar un proyecto de entorno de ejecución. Puedes verificar el estado de la vinculación del proyecto de tiempo de ejecución en la pestaña Asociaciones del proyecto de la página Configuración en la consola de Google Cloud .

    Ir al centro de APIs

Roles obligatorios

Para obtener los permisos que necesitas para crear y, luego, implementar un proxy de detección 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 si aún no está habilitada.

Roles necesarios para habilitar las APIs

Para habilitar APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

Habilitar la API

Configura las variables de entorno

En el proyecto Google Cloud 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. En el caso de Apigee Hybrid, esta es la región en la que se encuentra tu clúster.
  • RUNTIME_HOSTNAME es el nombre de host de tu entorno de ejecución de Apigee. En Apigee Hybrid, este es el nombre de host registrado en tu grupo de entornos de Apigee y que entrega tu puerta de enlace de entrada de Apigee (por ejemplo, api.example.com).

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

Cómo establecer el proyecto

Configura el proyecto Google Cloud 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 MCP Discovery Proxy. Después de implementar tu 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 las operaciones de tu 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 las operaciones de tu 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 la 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 del 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 del 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 detección de MCP. Esta coincidencia es necesaria para que las llamadas a 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 correspondiente del nombre de host 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 a través de 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 detección 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 detección 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 las operaciones de tu API, puedes crear un proxy de API nuevo con la plantilla MCP Discovery Proxy.

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

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

    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: Es un nombre para tu proxy.
    • Descripción (opcional): Es 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 explorador de archivos para seleccionar el archivo 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 el momento. 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 detección de MCP, puedes agregar políticas de seguridad para aplicar los requisitos de seguridad. Te recomendamos que protejas el acceso a tu proxy de detección 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 detección de MCP. Esto garantiza que todas las solicitudes al proxy de descubrimiento de MCP se autentiquen y autoricen. Si prefieres usar una clave de API, consulta Protege una API solicitando claves de API para conocer los pasos recomendados.

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

Para agregar la política VerifyAccessToken, sigue estos pasos:

  1. En la página de detalles del proxy, haz clic en la pestaña Desarrollar.
  2. En Proxy endpoints, haz clic en default 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 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 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 de nivel inferior. Durante este tiempo, que puede tardar varios minutos, la IU mostrará el estado Provisioning 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 implementar 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 implementó el proxy de detección de MCP.

Descubre las herramientas de MCP en el Centro de APIs

Una vez que se implementa tu proxy de descubrimiento de MCP, sus operaciones de API se transfieren 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 consola de Google Cloud , ve a la página Concentrador de APIs > APIs.

    Ir a APIs del concentrador de APIs

  2. Haz clic en Filtro y selecciona Estilo > MCP. Luego, haz clic en Aplicar.
  3. El proxy de MCP implementado debería aparecer en la lista. La canalización de transferencia del concentrador de APIs asigna automáticamente las rutas definidas en tu especificación de OpenAPI a las herramientas individuales de MCP que se enumeran en el concentrador.

Ahora, los desarrolladores de tu organización 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, enviarás una solicitud a tu extremo de MCP para inicializar tu servidor de MCP y confirmar que funciona según lo esperado.

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, enviarás 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 de 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 devuelve todas las herramientas que admite el extremo del 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 los agentes pueden descubrir tus herramientas de MCP con tu producto de API.

Supervisión y estadísticas

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

¿Qué sigue?