O Google Cloud API Gateway passou a funcionar, em prévia pública, como servidor MCP remoto. Uma empresa pode anotar uma especificação OpenAPI 3.x já usada por uma API REST e expor operações selecionadas como ferramentas descobertas por agentes, preservando autenticação, quotas e registros do gateway. O ganho é reduzir infraestrutura duplicada, mas a implantação exige escolher poucas operações, proteger a descoberta de ferramentas, limitar credenciais e testar consequências antes de permitir ações em produção.
Escolha uma operação estreita e verificável
Comece por uma API que já tenha proprietário, documentação, autenticação e registros confiáveis. Consultar o status de um pedido, localizar estoque de uma unidade ou abrir um chamado com campos definidos são melhores pilotos do que conceder acesso amplo a clientes, pagamentos ou configurações.
Escreva a decisão que o agente deve apoiar, quem pode solicitar a ação e qual resposta confirma sucesso. Se a equipe não consegue explicar o efeito de uma chamada REST hoje, convertê-la em ferramenta MCP apenas torna a ambiguidade mais fácil de acionar.
Prepare a especificação OpenAPI para o agente
O recurso aceita OpenAPI 3.0.x e 3.1.x; especificações 2.0 precisam ser migradas. A anotação x-google-api-management.mcp habilita MCP no documento, enquanto x-google-mcp-tool permite ajustar nome e descrição ou excluir uma operação. Cada operação exposta precisa de backend e descrição não vazia.
A descrição da ferramenta orienta o modelo sobre quando usá-la. Informe finalidade, condição de uso, parâmetros obrigatórios e situações em que a ferramenta não deve ser chamada. Nomes curtos ajudam, mas não substituem uma descrição que diferencie consultar, simular e executar.
- Expor apenas operações necessárias ao caso de uso
- Usar descrições que expliquem quando e por que chamar
- Separar consulta, simulação e alteração de estado
- Validar parâmetros, respostas e erros no contrato da API
Proteja descoberta e execução separadamente
O endpoint tools/list fica sem autenticação por padrão, o que pode revelar nomes e esquemas das ferramentas. Em produção, o Google recomenda exigir JWT para a descoberta; chaves de API não protegem esse método. Já tools/call aplica a autenticação configurada na operação REST subjacente.
Trate a credencial do agente como identidade de serviço com menor privilégio. Separe ambientes, restrinja público e origem quando possível, defina quotas por operação e mantenha ações sensíveis atrás de confirmação ou aprovação humana. Descobrir uma ferramenta e ter permissão para executá-la são controles diferentes.
Reaproveite quotas e registros sem perder contexto
O gateway converte chamadas MCP JSON-RPC em solicitações REST e aplica o mesmo caminho de políticas. Isso permite usar autenticação, quota e logging existentes em vez de manter regras paralelas em um servidor novo. A quota também é compartilhada entre tráfego REST e MCP para a mesma operação.
Adicione contexto útil aos registros: identidade do agente, usuário solicitante, sessão, ferramenta, parâmetros resumidos, resultado, latência e aprovação. Evite gravar dados pessoais ou segredos em texto aberto. Crie alertas para volume incomum, erros repetidos, tentativas de parâmetros inválidos e chamadas fora do horário esperado.
Teste falhas, ambiguidade e impacto operacional
Monte casos com pedido inexistente, permissões insuficientes, timeout, resposta incompleta, dado desatualizado e instrução conflitante. Verifique se o agente explica a falha sem inventar resultado, se evita repetição automática perigosa e se encaminha a pessoa quando a operação pode afetar cliente ou dinheiro.
Meça taxa de chamada correta, sucesso técnico, erro por parâmetro, tempo de resposta, custo, acionamentos desnecessários e intervenções humanas. Uma integração pode funcionar tecnicamente e ainda gerar pouco valor se chamar a ferramenta errada ou obrigar a equipe a revisar tudo depois.
Considere os limites da prévia pública
A prévia cobre backends REST com OpenAPI 3.x e mantém a autenticação existente. Recursos e prompts MCP, streaming de respostas e inspeção de payload pelo Model Armor ainda estão no roadmap. Operações com corpo vazio, como HTTP 204, não são expostas, esquemas profundamente aninhados podem não aparecer por completo e um gateway aceita até mil ferramentas.
MCP e model routing não podem ser habilitados na mesma configuração de API. Registre essas restrições no desenho, crie plano de reversão e acompanhe a documentação antes de ampliar. Para necessidades de ciclo de vida, políticas avançadas ou monetização, o próprio Google indica avaliar Apigee; para governar chamadas externas de agentes, indica Agent Gateway.
Para levar daqui
API Gateway com MCP pode acelerar a integração de agentes quando a empresa reaproveita contratos, autenticação, quotas e registros já confiáveis. Comece com poucas operações, proteja descoberta e execução, teste falhas e só amplie depois de medir chamadas corretas e impacto real.
