Começar a usar a Apigee e o MCP

Esta página se aplica a Apigee, mas não a Apigee híbrida.

Confira Apigee Edge documentação.

Esta página descreve como usar o proxy de descoberta da Apigee para disponibilizar suas APIs para clientes do Protocolo de Contexto de Modelo (MCP) em aplicativos de agente como ferramentas do MCP.

Antes de começar

Antes de começar, faça o seguinte:

  1. Faça login na sua Google Cloud conta do. Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.

  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. Confirme se você tem uma organização da Apigee provisionada. O proxy de descoberta do MCP está disponível para organizações de assinatura, pagamento por uso e avaliação. Para saber mais, consulte Introdução ao provisionamento.
  7. Confirme se você tem uma instância do hub de APIs da Apigee provisionada no seu Google Cloud projeto. Para mais informações, consulte Provisionar o hub de APIs no Google Cloud console. Para confirmar se o serviço do hub de APIs está ativado, confira a página Hub no Google Cloud console.

    Acesse o hub de API

  8. Confirme se uma instância da Apigee está anexada ao serviço do hub de APIs. O proxy de descoberta do MCP não tem suporte para uso com instâncias de plug-in da Apigee Edge para nuvem pública ou da Apigee Edge para nuvem privada no hub de APIs. Para mais informações, consulte Anexar um projeto de ambiente de execução. É possível verificar o status do anexo do projeto de ambiente de execução na guia Associações de projetos da página Configurações no Google Cloud console.

    Acesse o hub de API

Funções exigidas

Para receber as permissões necessárias para criar e implantar um proxy de descoberta do MCP, peça ao administrador para conceder a você o papel de administrador da Apigee (roles/apigee.admin) do IAM na conta de serviço usada para implantar proxies da Apigee. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando personalizados papéis ou outros predefinidos papéis.

Ativar APIs

Ative a API Apigee.

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

Ativar a API

Defina as variáveis de ambiente

No Google Cloud projeto que contém sua instância da Apigee, use o seguinte comando para definir variáveis de ambiente: 

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

Em que:

  • PROJECT_ID é o ID do projeto com sua instância da Apigee.
  • REGION é a Google Cloud região da sua instância da Apigee.
  • RUNTIME_HOSTNAME é o nome do host do ambiente de execução da Apigee.

Para confirmar se as variáveis de ambiente estão definidas corretamente, execute o comando a seguir e analise a saída: 

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

Defina o projeto

Defina o Google Cloud projeto no ambiente de desenvolvimento: 

    gcloud auth login
    gcloud config set project $PROJECT_ID

Visão geral

Para expor suas APIs como ferramentas do MCP usando a Apigee, crie e implante um novo proxy da Apigee usando o Proxy de descoberta do MCP modelo. Depois que o proxy for implantado, você poderá criar um produto de API para agrupar as operações de API do MCP no proxy em um produto de API. Como um produto de API, suas operações/ferramentas de API podem ser descobertas por clientes do MCP por meio da integração ao hub de APIs.

As seções a seguir descrevem as etapas para criar e implantar um proxy de descoberta do MCP, criar um produto de API e listar as ferramentas disponíveis:

  1. Crie uma especificação OpenAPI 3.0.x que descreva suas operações de API.
  2. Crie um proxy de descoberta do MCP.
  3. (Opcional) Adicione uma política de segurança ao proxy de descoberta do MCP.
  4. Implante o proxy de descoberta do MCP.
  5. (Opcional) Inicialize o servidor MCP.
  6. Liste as ferramentas disponíveis.

Crie uma especificação OpenAPI 3.0.x que descreva suas operações de API

Antes de criar e implantar o proxy de descoberta do MCP, é necessário criar uma especificação OpenAPI 3.0.x que descreva as operações de API que você quer expor como ferramentas do MCP. O MCP na Apigee oferece suporte às seguintes versões da OpenAPI:

  • 3.0.0
  • 3.0.1
  • 3.0.2
  • 3.0.3

Este guia de início rápido usa uma especificação OpenAPI 3.0.x de amostra com três operações de API:

  • GET /artists: retorna uma lista de artistas.
  • POST /artists: permite que um usuário poste um novo artista.
  • GET /artists/{username}: recebe informações sobre um artista do nome de usuário exclusivo dele.

Para criar a especificação OpenAPI 3.0.x, faça o seguinte:

  1. Crie um novo arquivo mcp-quickstart-openapi.yaml no diretório oas do pacote de proxy de API.
  2. Adicione o seguinte conteúdo ao arquivo: 
    # 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 correspondência de nome do host

É fundamental que o valor do nome do host no campo servers.url da especificação OpenAPI seja uma correspondência exata do nome do host do grupo de ambiente do ambiente da Apigee em que o proxy de descoberta do MCP está implantado. Essa correspondência é necessária para que as chamadas tools/list e tools/call funcionem corretamente.

A tabela a seguir mostra a configuração do nome do host na especificação OpenAPI e a configuração correspondente do nome do host no grupo de ambiente da Apigee:

Componente Configuração necessária Valor de exemplo Informações de apoio
Grupo de ambiente da Apigee Os nomes de host precisam ser configurados no grupo de ambiente. cymbal.products.com, internal.products.com Os grupos de ambiente permitem o roteamento para um grupo de ambientes usando um nome de host.
Especificação OpenAPI O valor do campo servers.url da especificação OpenAPI precisa ser uma correspondência exata do nome do host do grupo de ambiente do ambiente da Apigee em que o proxy de descoberta do MCP está implantado. https://cymbal.products.com Se o nome do host servers.url não corresponder ao nome do host do grupo de ambiente correspondente ao ambiente da Apigee em que o proxy de descoberta do MCP está implantado, você receberá um erro ao implantar o proxy.

Crie um proxy de descoberta do MCP

Agora que você tem uma especificação OpenAPI 3.0.x que define suas operações de API, é possível criar um novo proxy de API usando o modelo Proxy de descoberta do MCP.

Para criar um proxy de descoberta do MCP:

  1. Acesse a página Proxies de API no Google Cloud console.

    Acessar proxies de API

  2. Clique em + Criar para abrir o painel Criar proxy de API.
  3. Na caixa Modelo de proxy, selecione Proxy de descoberta do MCP.
  4. Na seção Detalhes do proxy, insira os seguintes detalhes:
    • Nome do proxy: um nome para o proxy.
    • Descrição (opcional): uma descrição para o proxy. Por exemplo, My first MCP Discovery Proxy.
  5. Clique em Próxima.
  6. Na seção Especificações OpenAPI, use o navegador de arquivos para selecionar o arquivo OpenAPI 3.0.x que você criou na etapa anterior.
  7. Clique em Próxima.
  8. Na seção Implantar (opcional), você pode pular a implantação do proxy por enquanto. Clique em Próxima.
  9. Clique em Criar.

Para conferir os endpoints de destino e do servidor do proxy, clique em Visualizar na coluna Resumo do endpoint da tabela Revisões. O Resumo do endpoint de revisão do proxy selecionado mostra as seguintes informações:

  • Endpoints do proxy: neste exemplo, o default endpoint do proxy com um caminho base de /mcp é exibido. Se outros nomes de host ou grupos de ambiente forem adicionados ao proxy, eles também serão exibidos aqui.
  • Endpoints de destino: neste exemplo, a conexão de destino default está definida como ORG_NAME.mcp.apigee.internal, em que ORG_NAME é o nome da sua organização da Apigee. O destino mcp.apigee.internal também tem suporte para compatibilidade com versões anteriores.

(Opcional) Adicione uma política de segurança ao proxy de descoberta do MCP

Antes de implantar o proxy de descoberta do MCP, você pode adicionar políticas de segurança para aplicar requisitos de segurança. Recomendamos que você proteja o acesso ao proxy de descoberta do MCP usando tokens OAuth ou uma chave de API.

Esta seção descreve como adicionar uma política OAuthV2 ao proxy de descoberta do MCP. Isso garante que todas as solicitações ao proxy de descoberta do MCP sejam autenticadas e autorizadas. Se você quiser usar uma chave de API, consulte Proteger uma API exigindo chaves de API para conferir as etapas recomendadas.

Para configurar a verificação de token, coloque uma política OAuthV2 com a operação VerifyAccessToken no início do fluxo do proxy de API (o início do pré-fluxo ProxyEndpoint). Se inseridos, os tokens de acesso serão verificados antes de qualquer outro processamento e, se um token for rejeitado, a Apigee interromperá o processamento e retornará um erro ao cliente.

Para adicionar a política VerifyAccessToken:

  1. Na página de detalhes do proxy, clique na guia Desenvolver.
  2. Em Endpoints do proxy, clique em padrão e depois em PreFlow.

  3. No editor de fluxo de proxy, clique em Adicionar etapa de política.

    Selecione PreFlow para um endpoint listado em Endpoints Proxy.
  4. Na caixa de diálogo Adicionar etapa de política, selecione Criar nova política.
  5. Na lista de políticas, em Segurança, selecione OAuth v2.0.
  6. Se quiser, altere o nome da política e o nome de exibição. Por exemplo, para uma melhor legibilidade, é possível alterar o Nome de exibição e o Nome para VerifyAccessToken.
  7. Clique em Adicionar.

Implante o proxy de descoberta do MCP

Para implantar o proxy de descoberta do MCP:

  1. Clique em Implantar para abrir o painel Implantar proxy de API.
  2. O campo Revisão precisa ser definido como 1. Se não for, clique em 1 para selecioná-lo.
  3. Na lista Ambiente, selecione o ambiente em que você quer implantar o proxy. O ambiente precisa ser abrangente.
  4. Insira a Conta de serviço que você criou em uma etapa anterior.
  5. Clique em Implantar.

Quando você clica em Implantar, a Apigee começa a implantar o proxy e provisionar componentes downstream. Durante esse período, que pode levar vários minutos, a UI vai mostrar um status de Provisionamento para a implantação.

Quando o processo for concluído, o status vai mudar para Implantado e o proxy estará pronto para processar o tráfego.

Depois que o proxy for implantado, confirme se o valor do nome do host no campo servers.url da especificação OpenAPI é uma correspondência exata do nome do host do grupo de ambiente do ambiente da Apigee em que o proxy de descoberta do MCP está implantado.

Descubra as ferramentas do MCP no hub de APIs

Depois que o proxy de descoberta do MCP for implantado, as operações de API dele serão ingeridas automaticamente no hub de APIs e disponibilizadas como ferramentas do MCP.

Para conferir as ferramentas do MCP no hub de APIs:

  1. No Google Cloud console, acesse a página Hub de APIs > APIs.

    Acessar APIs do hub das APIs

  2. Clique em Filtrar e selecione Estilo > MCP e clique em Aplicar.
  3. O proxy do MCP implantado vai aparecer na lista. O pipeline de ingestão do hub de APIs mapeia automaticamente os caminhos definidos na especificação OpenAPI para ferramentas individuais do MCP listadas no hub.

Os desenvolvedores da sua organização agora podem usar filtros ou a Pesquisa semântica no hub de APIs para encontrar ferramentas relevantes do MCP usando consultas em linguagem natural.

Inicialize o servidor MCP

Nesta etapa, você envia uma solicitação ao endpoint do MCP para inicializar o servidor do MCP e confirmar se ele está funcionando conforme o esperado.

Para inicializar e testar o servidor do MCP, envie a solicitação a seguir para o endpoint do 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"

Substitua:

  • MCP_ENDPOINT_URL: o URI base do endpoint do MCP. Por exemplo, cymbal.products.com.
  • MCP_PROTOCOL_VERSION: a versão do protocolo MCP. Por exemplo, 2025-11-25. Consulte Negociação de versão na especificação do MCP para mais informações.
  • (Opcional) TOKEN: token de acesso do OAuth 2.0

Uma resposta bem-sucedida é semelhante a esta:

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

Liste as ferramentas do MCP disponíveis

Nesta etapa, você envia uma solicitação para o método tools/list para confirmar a lista de ferramentas disponíveis no endpoint do MCP.

Envie uma solicitação para o método tools/list do proxy da 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"

Substitua:

  • MCP_ENDPOINT_URL: o URI base do endpoint do MCP. Por exemplo, cymbal.products.com.
  • MCP_PROTOCOL_VERSION: a versão do protocolo MCP. Por exemplo, 2025-11-25. Consulte o cabeçalho da versão do protocolo na especificação do MCP para mais informações.
  • (Opcional) TOKEN: token de acesso do OAuth 2.0

O método retorna todas as ferramentas com suporte do endpoint do MCP. Uma resposta bem-sucedida é semelhante a esta:

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

Agora que o endpoint está inicializado, as ferramentas do MCP podem ser descobertas por desenvolvedores e agentes usando o produto de API.

Monitoramento e análise

É possível monitorar o tráfego do MCP e conferir métricas no nível da ferramenta usando a Apigee Analytics. A Apigee Analytics permite filtrar métricas para distinguir entre o tráfego de API padrão e o tráfego específico do MCP, além de conferir o volume de uso de solicitações tools/list em comparação com tools/call. Para mais informações, consulte Monitorar e analisar o tráfego do MCP na Apigee.

A seguir