Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Comece a usar o Apigee e o MCP

Esta página aplica-se ao Apigee, mas não ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Esta página descreve como usar o proxy Apigee Discovery para disponibilizar as suas APIs aos clientes do Model Context Protocol (MCP) em aplicações de agentes como ferramentas do MCP.

Antes de começar

Antes de começar, conclua as seguintes tarefas:

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

Verify that billing is enabled for your Google Cloud project.

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

Verify that billing is enabled for your Google Cloud project.

Confirme que tem uma organização do Apigee aprovisionada. Para mais informações, consulte o artigo Introdução ao aprovisionamento
Confirme que tem uma instância do hub de APIs do Apigee aprovisionada no seu Google Cloud projeto. Para mais informações, consulte o artigo Aprovisione o hub de APIs na Google Cloud consola. Pode confirmar que o serviço do hub de APIs está ativado verificando a página Hub na Google Cloud consola.
Aceder ao hub de APIs
Confirme se existe uma instância do Apigee anexada ao seu serviço do API Hub. O proxy de deteção do MCP não é suportado para utilização com instâncias de plug-ins do Apigee Edge para nuvem pública ou Apigee Edge para nuvem privada no hub de APIs. Para mais informações, consulte o artigo Anexe um projeto de tempo de execução. Pode verificar o estado da associação do projeto de tempo de execução no separador Associações de projetos da página Definições na Google Cloud consola.
Aceder ao hub de APIs

Funções necessárias

Para receber as autorizações de que precisa para criar e implementar um proxy de deteção de MCP, peça ao seu administrador para lhe conceder a função do IAM Administrador do Apigee (roles/apigee.admin) na conta de serviço que usa para implementar proxies do Apigee. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Ativar APIs

Enable the Apigee API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Defina variáveis de ambiente

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

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

Onde:

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

Para confirmar que as variáveis de ambiente estão definidas corretamente, execute o seguinte comando e reveja o resultado:

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

Defina o projeto

Defina o Google Cloud projeto no seu ambiente de desenvolvimento:

    gcloud auth login
    gcloud config set project $PROJECT_ID

Vista geral

Para expor as suas APIs como ferramentas MCP através do Apigee, crie e implemente um novo proxy do Apigee com o modelo Proxy de deteção de MCP. Depois de implementar o proxy, pode criar um produto de API para agrupar as operações da API MCP no seu proxy num produto de API. Enquanto produto de API, as suas operações/ferramentas de API são detetáveis pelos clientes do MCP através da integração no hub de APIs.

As secções seguintes descrevem os passos para criar e implementar um proxy de descoberta do MCP, criar um produto API e listar as ferramentas disponíveis:

Crie uma especificação OpenAPI 3.0.x que descreva as operações da sua API.
Crie um proxy Discovery do MCP.
(Opcional) Adicione uma política de autenticação da Google ao proxy de deteção da MCP.
Implemente o proxy Discovery do MCP.
(Opcional) Crie um produto da API.
(Opcional) Crie um programador e uma app.
(Opcional) Inicialize o seu servidor MCP.
Indicar as ferramentas disponíveis.

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

Antes de criar e implementar o proxy de deteção do MCP, tem de criar uma especificação OpenAPI 3.0.x que descreva as operações da API que quer expor como ferramentas do MCP. Este início rápido usa uma especificação OpenAPI 3.0.x de exemplo com três operações de API:

GET/artists: devolve uma lista de artistas.
POST/artists: permite que um utilizador publique um novo artista.
GET /artists/{username}: obter informações sobre um artista a partir do respetivo nome de utilizador exclusivo.

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

Crie um novo ficheiro mcp-quickstart-openapi.yaml no diretório oas do pacote do proxy de API.

Adicione o seguinte conteúdo ao ficheiro:

# 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/v1
    description: Cymbal Group Production Server
  - url: https://internal.products.com/v1
    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 do nome do anfitrião

É fundamental que o valor do campo servers.url na especificação OpenAPI corresponda exatamente ao nome do anfitrião configurado no grupo de ambientes do Apigee correspondente ao ambiente do Apigee onde o proxy de deteção do MCP está implementado. Esta correspondência é necessária para que as chamadas tools/list e tools/call funcionem corretamente.

A tabela seguinte mostra a configuração do nome de anfitrião na especificação OpenAPI e a configuração do nome de anfitrião correspondente no grupo de ambientes do Apigee:

Componente	Configuração necessária	Exemplo de valor	Informações relevantes
Grupo de ambientes do Apigee	Os nomes de anfitrião têm de ser configurados no grupo de ambientes.	`cymbal.products.com`, `internal.products.com`	Os grupos de ambientes permitem o encaminhamento para um grupo de ambientes através de um nome de anfitrião.
Especificação OpenAPI	O valor de`servers.url` na especificação OpenAPI tem de corresponder exatamente a um nome de anfitrião do grupo de ambientes.	`https://cymbal.products.com`	Se o nome do anfitrião `servers.url` não corresponder ao nome do anfitrião do grupo de ambientes correspondente ao ambiente do Apigee onde o proxy de deteção do MCP está implementado, as chamadas `tools/list` e `tools/call` não funcionam.

Crie um proxy Discovery do MCP

Agora que tem uma especificação OpenAPI 3.0.x que define as suas operações de API, pode criar um novo proxy de API através do modelo MCP Discovery Proxy.

Para criar um proxy de descoberta de CPM:

Aceda à página Proxies de API na Google Cloud consola.
Aceda aos proxies de API
Clique em + Criar para abrir o painel Criar proxy de API.
Na caixa Modelo de proxy, selecione Proxy de descoberta do MCP.
Na secção Detalhes do proxy, introduza os seguintes detalhes:
- Nome do proxy: um nome para o seu proxy.
- Descrição (opcional): uma descrição para o seu proxy. Por exemplo, My first MCP Discovery Proxy.
Clicar em Seguinte.
Na secção Especificações da OpenAPI, use o explorador de ficheiros para selecionar o ficheiro OpenAPI 3.0.x que criou no passo anterior.
Clicar em Seguinte.
Na secção Implementar (opcional), pode ignorar a implementação do proxy por agora. Clique em Seguinte.
Clique em Criar.
Nota: a criação do proxy pode demorar até dez minutos. Quando a operação estiver concluída, acede à página de detalhes do Resumo do proxy, onde pode ver o seu proxy de deteção do MCP na página de detalhes do Resumo do proxy.

Pode ver o destino e os pontos finais do servidor do proxy clicando em Ver na coluna Resumo do ponto final da tabela Revisões. O Resumo do ponto final de revisão da revisão do proxy que selecionar apresenta as seguintes informações:

Pontos finais de proxy: neste exemplo, é apresentado o ponto final de proxy default com um caminho base de /mcp. Se forem adicionados nomes de anfitrião ou grupos de ambientes adicionais ao proxy, estes também são apresentados aqui.
Pontos finais de destino: neste exemplo, a ligação de destino default está definida como mcp.apigee.internal/mcp.

(Opcional) Adicione uma política ao proxy de deteção do MCP

Neste passo, adiciona a autenticação Google ao proxy de deteção do MCP. Ao adicionar a política de autenticação da Google, pode garantir que todos os pedidos ao proxy de deteção do MCP são autenticados e autorizados.

Para configurar a validação de tokens, coloque uma política OAuthV2 com a operação VerifyAccessToken no início do fluxo do proxy de API (o início do Preflow do ProxyEndpoint). Se forem colocados aí, os tokens de acesso são validados antes de qualquer outro processamento e, se um token for rejeitado, o Apigee para o processamento e devolve um erro ao cliente.

Para adicionar a política VerifyAccessToken:

Na página de detalhes do proxy, clique no separador Desenvolver.
Em Proxy endpoints (Pontos finais do proxy), clique em default (predefinição) e, de seguida, em PreFlow (PreFlow).
No editor de fluxo de proxy, clique em Adicionar etapa de política.
Na caixa de diálogo Adicionar etapa de política, selecione Criar nova política.
Na lista de políticas, em Segurança, selecione OAuth v2.0.
Opcionalmente, altere o nome da política e o nome a apresentar. Por exemplo, para melhorar a legibilidade, pode alterar o Nome a apresentar e o Nome para VerifyAccessToken.
Clique em Adicionar.

Implemente o proxy de descoberta do MCP

Para implementar o proxy de deteção do MCP:

Clique em Implementar para abrir o painel Implementar proxy de API.
O campo Revision deve ser definido como 1. Caso contrário, clique em 1 para a selecionar.
Na lista Ambiente, selecione o ambiente onde quer implementar o proxy. O ambiente tem de ser um ambiente Abrangente.
Introduza a conta de serviço que criou num passo anterior.
Clique em Implementar.

A configuração XML do proxy de API aparece no separador Desenvolver.

Depois de implementar o proxy, confirme o seguinte:

O campo servers.url na especificação OpenAPI corresponde exatamente ao hostname configurado no grupo de ambientes do Apigee correspondente ao ambiente do Apigee onde o proxy de descoberta do MCP está implementado.
O hub de APIs contém o proxy que acabou de implementar e está configurado com o estilo MCP. Para confirmar, aceda à página API Hub → APIs na Google Cloud consola e filtre pelo estilo de API MCPs.
Aceda às APIs do hub de APIs

(Opcional) Crie um produto de API

Neste passo, crie um produto API que agrupe as operações e os pontos finais no seu proxy que quer expor a programadores ou agentes. Este passo é opcional. Se não precisar de autenticação para chamar o método tools/list no seu ponto final do MCP, pode ignorar este passo e avançar para inicializar o seu servidor MCP.

Para criar um produto de API:

Na Google Cloud consola, aceda à página Produtos de API.
Aceda a produtos API
Clique em add Criar. É apresentada a página Detalhes do produto. Na secção Detalhes do produto, introduza os seguintes detalhes:
- Nome: um nome para o seu produto de API. Por exemplo, MCP API product.
- Nome a apresentar: um nome a apresentar para o seu produto da API. Por exemplo, MCP product.
- Description: uma descrição do seu produto de API. Por exemplo, API product for hostname cymbal.products.com.
- Ambiente: introduza o ambiente onde implementou o proxy de deteção do MCP. Por exemplo, default.
- Acesso: selecione Público.
- Quota: pode ignorar este campo para este tutorial.
- Âmbito de OAuth permitido: introduza as suas operações como uma lista separada por vírgulas. Para este tutorial, introduza artists.get, artists.post, artists.username.get.
Na secção Operações, clique em + Adicionar uma operação para abrir o painel Operação.
No painel Operação:
1. Filtre ou desloque a página para encontrar e selecionar o seu proxy de descoberta do MCP na lista de proxies.
2. Na secção Operation, introduza o Path e os Methods no caminho do recurso que quer incluir no produto da API. Para este tutorial:
  - Caminho: introduza/.
  - Métodos: selecione POST.
3. Clique em Guardar.

Quando o produto API é criado, é apresentada a página Detalhes do produto. O produto API está agora pronto para ser publicado no seu portal do programador e disponibilizado a programadores e agentes.

(Opcional) Crie um programador e uma app

Neste passo, cria um programador e uma app na sua organização do Apigee e usa estes recursos para testar o seu ponto final do MCP. Este passo é opcional. Se não precisar de autenticação para chamar o método tools/list no seu ponto final do MCP, pode ignorar este passo e avançar para inicializar o seu servidor MCP.

Para configurar os recursos de que precisa para os testes:

Aceda à página Gestão de APIs da Apigee na Google Cloud consola:
Gestão de APIs da Apigee
Selecione a organização do Apigee onde instalou o operador do Apigee para Kubernetes.
Crie um programador:
1. Selecione Distribuição > Programadores.
2. Na página Programadores, clique em + Criar.
3. Na página Adicionar programador, preencha os campos obrigatórios com os valores que quiser.
4. Clique em Adicionar.
Crie uma app:
1. Selecione Distribuição> Apps.
2. Na página Apps, clique em + Criar
3. Na página Criar app, preencha os campos obrigatórios na secção Detalhes da app com os seguintes valores:
  - Nome da app: mcp-test-app
  - Programador: selecione o programador que criou no passo anterior ou outro programador da lista.
4. Na secção Credenciais da app, clique em + Adicionar credencial.
5. Na secção Credencial, preencha os campos obrigatórios na secção Detalhes da credencial com os seguintes valores:
  - Nome da credencial: demo-credential
  - Tipo de credencial: selecione Chave da API.
6. Clique em Criar.
7. Na secção Produtos, clique em + Adicionar produtos.
8. Selecione o api-product-1 criado no passo anterior.
9. Clique em Adicionar.
10. Clique em Criar.
Na página Detalhes da app, na secção Credencial, clique em para apresentar o valor da Chave.
Copie o valor Key. Vai usar esta chave para fazer chamadas API ao seu serviço num passo posterior.
Na página Detalhes da app, na secção Credencial, clique em para apresentar o valor do segredo da app.
Copie o valor do segredo da app. Vai usar este valor para gerar um token de acesso num passo posterior.

Inicialize o servidor MCP

Neste passo, envia um pedido para o seu ponto final do MCP para inicializar o servidor MCP e confirmar que está a funcionar conforme esperado.

Para inicializar e testar o servidor MCP, envie o seguinte pedido para o ponto final do MCP:

curl -X POST "https://MCP_ENDPOINT_URL/mcp" \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": 1,
        "method": "initialize",
        "params": {}
      }' \
  -H "Authorization: Bearer TOKEN"

Substitua o seguinte:

MCP_ENDPOINT_URL: o URI base do ponto final do MCP. Por exemplo, cymbal.products.com.
(Opcional) TOKEN: chave de acesso OAuth 2.0

Uma resposta bem-sucedida tem um aspeto semelhante ao seguinte:

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

Liste as ferramentas MCP disponíveis no seu produto API

Neste passo, envia um pedido ao método tools/list para confirmar a lista de ferramentas disponíveis no seu ponto final do MCP.

Nota: pode controlar a autenticação para o método tools/list ao nível do produto da API. Se a autenticação não for necessária para aceder ao seu ponto final do MCP, o proxy de descoberta do MCP não tem de fazer parte de um produto API. No entanto, tenha em atenção que permitir o acesso não autenticado ao método pode representar um risco de segurança para a sua organização.

Envie um pedido para o método tools/list do seu proxy do Apigee:

curl -X POST "https://MCP_ENDPOINT_URL/mcp" \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/list",
        "params": {}
      }' \
  -H "Authorization: Bearer TOKEN"

Substitua o seguinte:

MCP_ENDPOINT_URL: o URI base do ponto final do MCP. Por exemplo, cymbal.products.com.
(Opcional) TOKEN: chave de acesso OAuth 2.0

O método devolve todas as ferramentas que o ponto final do MCP suporta. Uma resposta bem-sucedida tem um aspeto semelhante ao seguinte:

{
  "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 seu ponto final está inicializado, os programadores e os agentes podem descobrir as suas ferramentas MCP através do seu produto API.

Resolução de problemas

As secções seguintes descrevem os erros e os problemas conhecidos que pode encontrar ao usar o MCP no Apigee.

Os pedidos API falham quando `servers.url` inclui um caminho base

Problema: se configurar um proxy de deteção de APIs com uma especificação OpenAPI em que o campo servers.url contém um segmento de caminho (como https://example.com/mypath), os pedidos de API feitos através do MCP podem falhar.

Sintomas: as chamadas API para ferramentas MCP configuradas com estas especificações OpenAPI podem resultar em erros como 404 Not Found, mesmo que o comando tools/list mostre a ferramenta com êxito.

Causa: o servidor MCP processa incorretamente o elemento servers.url, removendo o segmento do caminho (por exemplo, /mypath). Isto resulta no encaminhamento das chamadas da API sem o caminho base necessário.

Solução alternativa: modifique a especificação OpenAPI para incluir o caminho base de servers.url no início de cada caminho definido na secção paths. Por exemplo:

# 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: # use the hostname from the environment group
  - url: https://cymbal.products.com/v1
    description: Cymbal Group Production Server
paths:
  /v1/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

paths

O servidor nativo do MCP devolve 404 para `tools/call`

Problema: as tentativas de usar mcp: tools/call resultam num erro 404 Not Found do servidor OneMCP. Isto pode ocorrer mesmo nos casos em que o método mcp: tools/list funciona conforme esperado.

Sintomas: quando usa o mcp: tools/call, recebe uma resposta de erro 404 semelhante à seguinte:

"MCP error -32001: Error POSTing to endpoint (HTTP 404):"

Causa: normalmente, este problema é causado pelo processamento incorreto do caminho base na especificação OpenAPI, conforme descrito no artigo As solicitações de API falham quando o OpenAPI servers.url inclui um caminho base. O servidor MCP não consegue encontrar o recurso correto porque o caminho da API que está a procurar não inclui o caminho base necessário.

Solução alternativa: aplique a solução alternativa detalhada no artigo Os pedidos de API falham quando o OpenAPI servers.url inclui um caminho base. Certifique-se de que todos os caminhos na sua especificação OpenAPI têm o prefixo do caminho base extraído de servers.url.

Erro de análise de JSON ao enviar o pedido para o ponto final do MCP

Pode receber uma mensagem de erro semelhante à seguinte (ou com um código e uma mensagem de erro diferentes) quando envia um pedido para o seu ponto final do MCP:

{
  "error": {
    "code": -32700,
    "message": "JSON parse error"
  },
  "id": null,
  "jsonrpc": "2.0"
}

Nesse caso, recomendamos que confirme as seguintes informações:

Introduziu o URL de ponto final do MCP correto.
O seu pedido está formatado corretamente.
Está a aceder a um método suportado.
Ativou e configurou o proxy de deteção do MCP numa região suportada

Se encontrar outros problemas, consulte o artigo Usar a depuração para ver informações detalhadas sobre a utilização da ferramenta de depuração na Google Cloud consola para analisar pedidos e respostas de e para o seu proxy de deteção de MCP.