Esta página se aplica à Apigee e à Apigee híbrida.
Confira a documentação da
Apigee Edge.
Nesta página, descrevemos como usar a Apigee para expor suas APIs
como ferramentas do MCP para aplicativos de agentes. O MCP na Apigee está disponível para organizações de
assinatura, pagamento por uso e avaliação, incluindo
organizações com residência de dados ativada. A partir da versão 1.17.0 da Apigee híbrida, o MCP também está disponível para a Apigee híbrida. O plano de dados de ambiente de execução é executado no seu próprio cluster do Kubernetes, e não em uma infraestrutura gerenciada pelo Google. Consulte
Ativar o MCP na Apigee híbrida
para o fluxo de instalação e configuração específico da Hybrid.
O que é o MCP?
O Protocolo de Contexto de Modelo (MCP) é um protocolo de código aberto desenvolvido pela Anthropic que padroniza a maneira como os aplicativos de IA se conectam a fontes de dados, fluxos de trabalho e ferramentas.
Os aplicativos de IA podem usar o MCP para acessar Google Cloud e os serviços da Apigee como ferramentas. Nesse contexto, é útil entender os seguintes termos do MCP:
- Host do MCP:o aplicativo ou ambiente de IA que interage com o usuário. O host do MCP usa modelos de linguagem grandes (LLMs) para processar solicitações que podem exigir dados ou ferramentas externas.
- Cliente MCP:um componente no host MCP que ajuda o LLM e o servidor MCP a se comunicarem entre si. Ele traduz as solicitações do LLM para o servidor MCP e converte as respostas do servidor MCP para o LLM. Ele também encontra e usa servidores MCP disponíveis.
- Servidor MCP:o serviço externo que fornece contexto, dados ou recursos ao LLM, atuando como um proxy entre o LLM e o cliente MCP.
Como o MCP funciona na Apigee
Os endpoints do MCP para Google, Google Cloude Apigee implementam a especificação do servidor MCP. Isso permite que clientes compatíveis com o MCP acessem os dados para:
- Descubra os endpoints disponíveis.
- Liste as ferramentas disponíveis em um endpoint.
- Autentique-se em um endpoint.
- Chame ferramentas de acordo com as políticas de acesso definidas.
Qualquer cliente do MCP que ofereça suporte a endpoints remotos do MCP em HTTP/S pode acessar essas ferramentas.
Como os endpoints são gerenciados, não é necessário instalar ou gerenciar servidores MCP locais ou remotos nem infraestrutura adicional para
permitir que aplicativos com agentes acessem seus serviços.
O MCP na Apigee oferece suporte a JSON-RPC para métodos tools/list e tools/call. É possível personalizar seu endpoint do MCP com parâmetros de capacidade de descoberta, segurança, disponibilidade de rede e capacidade de observação.
Modelos de implantação
O MCP está disponível em dois modelos de implantação da Apigee:
- Apigee (SaaS): o plano de dados do MCP é hospedado em uma infraestrutura gerenciada pelo Google. Você implanta o proxy de descoberta do MCP, e o endpoint fica disponível imediatamente.
- Apigee híbrida (autohospedada, a partir da Apigee híbrida
1.17.0): o plano de dados do MCP é executado no seu próprio cluster do Kubernetes. O plano de controle do Apigee gera a configuração da ferramenta MCP com base na sua especificação OpenAPI, e o cluster busca essa configuração no próprio cronograma. O tráfego de solicitações do MCP nunca sai do seu cluster. Consulte Ativar o MCP na Apigee híbrida.
Arquitetura do plano de dados do MCP na Apigee híbrida
O diagrama a seguir mostra como os componentes do MCP são distribuídos entre o plano de controle da Apigee e o cluster do Apigee híbrida.
Duas propriedades dessa arquitetura são importantes para o planejamento e a revisão de segurança:
- O tráfego de solicitações do MCP permanece dentro do cluster. Os clientes do MCP acessam o ingresso da Apigee no mesmo URL que usariam para qualquer outro proxy da Apigee. Em seguida, o processador de mensagens encaminha a solicitação para o plano de dados do MCP no mesmo cluster. Nenhuma solicitação ou resposta do MCP cruza o limite para Google Cloud no momento da solicitação.
- A configuração é extraída, não enviada por push. A configuração da ferramenta MCP é gerada pelo plano de controle da Apigee e recuperada por um componente no seu cluster de acordo com uma programação. O plano de controle da Apigee nunca inicia uma conexão com seu cluster. Consulte Requisitos de rede de saída para conferir os endpoints exatos que a saída do cluster precisa permitir.
Principais recursos do MCP na Apigee
O MCP na Apigee oferece recursos para descoberta, segurança e governança de ferramentas. Esses recursos ajudam você a gerenciar como os aplicativos de agente interagem com seus serviços.
Descoberta simplificada de ferramentas com o hub de APIs
É possível descobrir os endpoints do MCP disponíveis para serviços da Apigee usando um serviço de diretório acessível por uma interface REST. Cada endpoint do MCP também é compatível com o método tools/list do MCP, que permite que os clientes do MCP descubram as ferramentas disponíveis nesse endpoint.
Além disso, a MCP se integra ao hub de APIs da Apigee. Quando um proxy de descoberta do MCP é implantado, o hub de API ingere automaticamente a especificação OpenAPI, atribui a ela o estilo de API MCP e mapeia as operações de API para ferramentas individuais do MCP. Assim, os desenvolvedores podem filtrar facilmente as APIs compatíveis com MCP no hub de APIs e usar a Pesquisa semântica com consultas em linguagem natural para encontrar ferramentas relevantes para os aplicativos de agente.
Segurança
O MCP na Apigee inclui várias camadas de segurança para proteger seus serviços. É possível controlar o acesso usando autenticação, autorização, limites de rede e verificação de conteúdo.
Autenticação
Os endpoints do MCP hospedados pelo Apigee são compatíveis com OAuth 2.1 e OpenID Connect (OIDC) para autenticação. Isso garante que apenas agentes, clientes do MCP e usuários finais com identidades estabelecidas possam acessar seus endpoints do MCP e chamar as ferramentas do MCP. Com os metadados de recursos protegidos, os clientes descobrem os servidores de autorização do OAuth.
Políticas de autorização detalhada
É possível restringir o acesso às ferramentas do MCP com base nas identidades do cliente OAuth. Por exemplo, é possível configurar uma política no proxy de descoberta do MCP para especificar que apenas agentes designados com identidades de cliente conhecidas podem acessar uma ferramenta do MCP para um serviço de pagamentos.
Responsabilidade do cliente pelas invocações de ferramentas
Os aplicativos cliente do MCP são responsáveis por aplicar a supervisão humana das invocações de ferramentas, como pedir que o usuário confirme antes de executar operações de mudança de estado. Para mais informações, consulte a documentação do protocolo de contexto do modelo.
Observabilidade e análise
Para endpoints hospedados da Apigee, use o Apigee Analytics para conferir informações detalhadas de uso das suas ferramentas do MCP.
O Google Analytics permite segmentar o tráfego específico da MCP do tráfego padrão da API e ver métricas no nível da ferramenta individual, como o volume de solicitações de tools/list (descoberta) e tools/call (execução). As métricas de performance também ajudam a distinguir
entre a sobrecarga do proxy e o tempo de resposta pretendido, permitindo que você
identifique gargalos com mais eficiência.
Confiabilidade e solução de problemas
Para melhorar a solução de problemas e oferecer mais visibilidade ao processo de implantação, o Apigee mostra erros específicos de infraestrutura e configuração na UI. Se uma implantação falhar devido a uma especificação OpenAPI inválida ou a um problema de infraestrutura regional, a UI vai fornecer feedback útil para ajudar você a resolver o problema sem precisar de intervenção do suporte.
Como usar o MCP com a Apigee
Você pode expor suas APIs da Apigee atuais como ferramentas do MCP e torná-las acessíveis por endpoints do MCP.
Esses endpoints podem ser configurados por host ou por grupo de ambientes. Por exemplo, se a organização cymbal tiver oito nomes de host (por exemplo, api.cymbal.com, partners.cymbal.com), cada um associado a um grupo de ambiente diferente, você poderá hospedar um servidor MCP dedicado para cada nome de host.
Um endpoint de destino gerenciado (ORG_NAME.mcp.apigee.internal) é implantado usando um proxy especializado de descoberta do MCP na sua organização do Apigee, onde os servidores do MCP são disponibilizados.
A tabela a seguir mostra um exemplo de como os clientes, incluindo a organização fictícia de pratos, podem configurar vários endpoints do MCP usando o Apigee.
| Cliente | Nome do host e basepath do MCP | Endpoint de destino do servidor MCP | Proxy de API | Ambiente / Grupo de ambientes |
|---|---|---|---|---|
| címbalo | api.cymbal.com/mcp |
cymbal.mcp.apigee.internal(projeto de locatário da organização cymbal) |
mcp-api-proxy1 |
prod / prod-env-group |
api-internal.cymbal.com/mcp |
cymbal.mcp.apigee.internal(projeto de locatário da organização cymbal) |
mcp-api-proxy2 |
internal / internal-env-group |
|
api-service.cymbal.com/mcp |
cymbal.mcp.apigee.internal(projeto de locatário da organização cymbal) |
mcp-api-proxy3 |
dev / dev-env-group |
Limitações
As seguintes limitações se aplicam ao MCP no Apigee:
- O número de ferramentas do MCP em uma organização da Apigee é limitado a 1.000.
- A implantação da infraestrutura do MCP pode estar sujeita a limitações de capacidade nas seguintes regiões:
europe-central2europe-southwest1europe-west9me-central2
Se você encontrar um erro de provisionamento ou se o status nunca mudar para Implantado, isso pode ser devido a limites temporários de capacidade da infraestrutura na região selecionada. Tente implantar o proxy em um ambiente de outra região.
- O MCP na Apigee é compatível com as seguintes versões do OpenAPI: 3.0.0, 3.0.1, 3.0.2. 3.0.3.
- Os insights de API no hub de API da Apigee não estão disponíveis para APIs e ferramentas do MCP implantadas em organizações da Apigee com o VPC-SC ativado.
- As chamadas GET em respostas de erro do MCP vão retornar um erro
405, já que o servidor MCP não aceita streams de eventos enviados pelo servidor (SSE, na sigla em inglês). - Os insights da API do hub de APIs da Apigee não vão mostrar APIs ou tráfego no estilo MCP para recursos do MCP até que a versão 1-17-0-apigee-6 da Apigee seja totalmente lançada em todas as regiões disponíveis.
- Não é possível mudar o atributo de estilo da API para MCP em um recurso de API que já tenha operações.
Limitações específicas da Apigee híbrida
As seguintes limitações se aplicam ao MCP na Apigee híbrida:
- A contagem de ferramentas do MCP é limitada por tamanho, não por um número fixo. Ao contrário da Apigee, que impõe um número máximo fixo de ferramentas do MCP por organização, a Apigee híbrida limita a capacidade da ferramenta com quatro limites de tamanho: tamanho do arquivo de especificação OpenAPI, tamanho do pacote de proxy do MCP, tamanho da resposta
tools/listpor nome do host e número de nomes de host por grupo de ambiente. Para a maioria das especificações OpenAPI, é possível incluir 10.000 ferramentas do MCP por organização no limite de tamanho de resposta padrão. A capacidade real varia de acordo com a forma específica da sua especificação (dominada pelo número de parâmetros e propriedades do corpo da solicitação, além do comprimento da descrição). Os esquemas de resposta não são contabilizados no orçamento. Para estimar a capacidade das suas especificações OpenAPI e conferir os quatro limites máximos e os modos de falha deles, consulte Estimar a capacidade da ferramenta MCP. - Ativar ou desativar o MCP aciona um lançamento de versão canário em etapas de pods do processador de mensagens. O operador da Apigee atualiza a especificação do pod do processador de mensagens
quando você ativa ou desativa o MCP, e o controlador do processador de mensagens
ApigeeDeploymentexecuta a mudança por uma versão canário em etapas, em vez de uma reinicialização gradual do Kubernetes simples. A liberação é acionada apenas nas transições de ativação e desativação, não na atividade de implantação do MCP em andamento ou no tráfego do MCP em estado estável. Programe a ativação inicial e as operações de desativação subsequentes durante uma janela de manutenção aprovada. - O dimensionamento de recursos do pod do MCP é gerenciado pelo cliente. Os pods do MCP são executados com as solicitações e os limites de recursos definidos pelos padrões integrados nos gráficos do Helm da Apigee híbrida. Se a carga de trabalho exigir mais capacidade, ajuste a CPU e a memória em
overrides.yaml. Consulte a referência do campooverrides.yamlpara ver os campos disponíveis. - Um plano de dados do MCP por organização da Apigee e por cluster. Na versão
1.17.0, o operador da Apigee provisiona um plano de dados do MCP para cada organização da Apigee instalada no cluster. Um cluster que hospeda várias organizações da Apigee executa um plano de dados do MCP por organização. Os planos de dados são independentes e não compartilham configuração. - É necessário ativar de forma uniforme em um grupo de ambientes. Ative o MCP
de maneira uniforme em todos os clusters que atendem ao mesmo grupo de ambientes da Apigee. Se o MCP estiver
ativado em alguns clusters e não em outros dentro de um grupo, as solicitações do MCP que forem encaminhadas para um
cluster sem o MCP ativado vão receber uma resposta
503 Service Unavailable. - TLS unidirecional entre o processador de mensagens e o plano de dados do MCP. A versão
1.17.0usa o TLS unidirecional entre o processador de mensagens e o plano de dados do MCP. - O plano de dados do MCP depende do processador de mensagens para a identidade do autor da chamada. O plano de dados do MCP no cluster não autentica de forma independente os chamadores em
1.17.0. Ele confia que as solicitações que chegam a ele já foram autenticadas por um proxy da Apigee em execução no processador de mensagens. Todas as solicitações de MCP que precisam ser autenticadas chegam por um proxy do MCP da Apigee que aplica uma política de autenticação. Consulte Gerenciar o acesso à ferramenta MCP. Os clientes Production precisam aplicar controles de entrada de cluster para que apenas pods do processador de mensagens (rótulo do Kubernetesapp=apigee-runtimeno mesmo namespace do Kubernetes em que o Apigee híbrido está instalado) possam acessar o serviço MCP em TCP443. Use o mecanismo de política compatível com sua plataforma (Kubernetes NetworkPolicy, Cilium, Calico, Istio AuthorizationPolicy) para aplicar essa restrição.
A seguir
- Saiba como começar a usar a Apigee e o MCP.
- Para a Apigee híbrida, primeiro ative o MCP no cluster e siga o guia de início rápido.
- Para acessar outros produtos do Google e do Google Cloud com as ferramentas do MCP, consulte Visão geral dos servidores MCP do Google Cloud.