Começar a usar a Apigee e o MCP

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Nesta página, descrevemos como usar o proxy de descoberta da Apigee para disponibilizar suas APIs para clientes do Protocolo de Contexto de Modelo (MCP) em aplicativos de agentes como ferramentas do MCP.

Antes de começar

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

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, 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 sem custos financeiros.

  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, além da Apigee híbrida versão 1.17.0 e posteriores. Para saber mais, consulte Introdução ao provisionamento.
  7. Somente Apigee híbrida:confirme se você concluiu as etapas de ativação única do cluster descritas em Ativar o MCP na Apigee híbrida. Isso envolve definir enableMcpServer: true como uma chave de nível superior no overrides.yaml e executar helm upgrade nos gráficos apigee-operator e apigee-org.
  8. Confirme se você tem uma instância do hub de APIs da Apigee provisionada no seu projeto do Google Cloud . Para mais informações, consulte Provisionar o hub de APIs no console do Google Cloud . Para confirmar se o serviço do hub de APIs está ativado, verifique a página Hub no console do Google Cloud .

    Acesse o hub de API

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

    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 do IAM de Administrador da Apigee (roles/apigee.admin) 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 papéis personalizados ou outros papéis predefinidos.

Ativar APIs

Ative a API Apigee, se ainda não tiver feito isso.

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

Ativar a API

Defina as variáveis de ambiente

No projeto do Google Cloud 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 região Google Cloud da instância da Apigee. Para a Apigee híbrida, essa é a região em que o cluster está localizado.
  • RUNTIME_HOSTNAME é o nome do host do ambiente de execução da Apigee. Para a Apigee híbrida, esse é o nome do host registrado no grupo de ambientes da Apigee e disponibilizado pelo gateway de entrada da Apigee (por exemplo, api.example.com).

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

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

Defina o projeto:

Defina o projeto do Google Cloud no ambiente de desenvolvimento: 

    gcloud auth login
    gcloud config set project $PROJECT_ID

Visão geral

Para expor suas APIs como ferramentas MCP usando a Apigee, crie e implante um novo proxy da Apigee usando o modelo Proxy de descoberta MCP. Depois que o proxy for implantado, você poderá criar um produto de API para agrupar as operações da API 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 com o 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 as operações da 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. Lista as ferramentas disponíveis.

Criar uma especificação OpenAPI 3.0.x que descreva as operações da API

Antes de criar e implantar o proxy de descoberta do MCP, é preciso 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 é compatível com as 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 um exemplo de especificação OpenAPI 3.0.x 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}: obtenha informações sobre um artista usando o 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 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 da OpenAPI e a configuração correspondente no grupo de ambientes da Apigee:

Componente Configuração necessária Valor de exemplo Informações de apoio
Grupo de ambientes 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 ambientes 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ê vai receber um erro ao implantar o proxy.

Criar um proxy de descoberta do MCP

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

Para criar um proxy de descoberta do MCP:

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

    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 as seguintes informações:
    • Nome do proxy: um nome para o proxy.
    • Descrição (opcional): uma descrição do proxy. Por exemplo, My first MCP Discovery Proxy.
  5. Clique em Próxima.
  6. Na seção Especificações da 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), pule a implantação do proxy por enquanto. Clique em Next.
  9. Clique em Criar.

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

  • Endpoints de proxy: neste exemplo, o endpoint de proxy default com um caminho base de /mcp é exibido. Se outros nomes de host ou grupos de ambiente forem adicionados ao proxy, eles também vão aparecer 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 é compatível com versões anteriores.

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

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

Nesta seção, descrevemos como adicionar uma política OAuthV2 ao proxy de descoberta do MCP. Isso garante que todas as solicitações para o 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 ver 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 ProxyEndpoint Preflow). Se colocados lá, os tokens de acesso serão verificados antes de qualquer outro processamento. 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 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 melhorar a legibilidade, mude o Nome de exibição e o Nome para VerifyAccessToken.
  7. Clique em Adicionar.

Implantar 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. Caso contrário, 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 o status Provisionando para a implantação.

Quando o processo é concluído, o status muda para Implantado, e o proxy está 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 da OpenAPI é uma correspondência exata do nome do host do grupo de ambiente da Apigee em que o proxy de descoberta do MCP está implantado.

Descobrir ferramentas do MCP no hub de APIs

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

Para conferir suas ferramentas do MCP no hub de APIs:

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

    Acessar APIs do hub das APIs

  2. Clique em Filtrar e selecione Estilo > MCP. Depois, clique em Aplicar.
  3. O proxy 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 as ferramentas MCP individuais 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.

Inicializar o servidor MCP

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

Para inicializar e testar o servidor MCP, envie a seguinte solicitação ao 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"
      }
    }
  }

Listar ferramentas do MCP disponíveis

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

Envie uma solicitação ao método tools/list para o 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 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 compatíveis com o 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 foi inicializado, as ferramentas do MCP podem ser descobertas por desenvolvedores e agentes que usam seu produto de API.

Monitoramento e análise

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

A seguir