Visão geral do Protocolo de Contexto de Modelo

Este documento oferece uma visão geral do suporte ao Protocolo de Contexto de Modelo (MCP) no gateway de API.

O API Gateway pode atuar como um servidor MCP remoto, permitindo que você exponha suas APIs REST atuais a agentes de IA e LLMs sem reescrever os serviços de back-end.

Contexto

O Protocolo de Contexto de Modelo (MCP) é um padrão aberto que permite criar agentes de IA diretamente na sua infraestrutura atual. Em vez de escrever um código de integração personalizado para cada ferramenta ou API, o MCP oferece uma maneira padrão para que os modelos de IA descubram e invoquem funcionalidades no seu ambiente.

Quando configurado como um servidor MCP, o gateway de API atua como um proxy. Ele traduz mensagens padrão do protocolo JSON-RPC do MCP enviadas de sistemas de agentes em solicitações HTTP REST padrão para seus back-ends atuais.

Recursos compatíveis

Durante o Acesso antecipado, o gateway de API é compatível com os seguintes recursos do MCP:

  • Servidor MCP remoto: o API Gateway atua como um servidor remoto, recebendo solicitações MCP via HTTP (POST).
  • Integração do OpenAPI 3.x: a configuração do MCP é derivada diretamente da sua especificação OpenAPI 3.x usando extensões personalizadas.
  • Métodos de ciclo de vida do MCP compatíveis:
    • initialize: estabelece a versão e os recursos do protocolo.
    • notifications/initialized: confirma o handshake.
    • tools/list: permite que os clientes descubram as ferramentas disponíveis e os esquemas delas.
    • tools/call: permite que os clientes invoquem uma ferramenta com argumentos.

Limitações

As seguintes limitações se aplicam ao suporte do MCP no gateway de API:

  • Recursos (resources/*) e comandos (prompts/*) não são compatíveis.
  • O transporte stdio não é compatível.
  • O OpenAPI 2.0 não é compatível.
  • Não é possível fazer streaming nem chamadas de ferramentas de longa duração.
  • Exclusão mútua de roteamento de modelo: não é possível ativar o MCP e o roteamento de modelo na mesma configuração de API. Se x-google-api-management.mcp estiver ativado, não será possível usar x-google-model-router.

Para uma lista completa de limites técnicos, consulte Limitações de recursos da OpenAPI 3.x.

Casos de uso

  • Exponha APIs REST atuais como ferramentas do MCP: transforme suas APIs atuais em ferramentas prontas para IA sem mudar o código de back-end.
  • Selecionar ferramentas por operação: escolha explicitamente quais caminhos e métodos de API são expostos aos agentes.
  • Proteja a superfície da ferramenta: aplique as políticas de segurança do gateway de API (como chaves de API ou OAuth) ao endpoint do MCP.

Fluxo da solicitação

O caminho canônico para solicitações da MCP é <basepath>/mcp, em que <basepath> é derivado do URL do gateway ou da configuração x-google-endpoint.

O diagrama a seguir mostra o fluxo de solicitação de uma solicitação tools/call do MCP:

  1. Um cliente MCP (por exemplo, um agente de IA) envia uma solicitação JSON-RPC ao endpoint MCP do gateway (por exemplo, POST /mcp ou POST /v1/mcp se um prefixo de versão for usado).
  2. O gateway valida a solicitação e verifica a autenticação.
  3. O gateway inspeciona o payload para determinar qual ferramenta está sendo chamada.
  4. O gateway traduz o payload do MCP em uma solicitação HTTP padrão (caminho, parâmetros, corpo) com base no mapeamento definido na configuração da API.
  5. O gateway encaminha a solicitação para o serviço de back-end.
  6. O back-end retorna uma resposta HTTP padrão.
  7. O gateway traduz a resposta HTTP de volta para uma resposta JSON-RPC do MCP e a retorna ao cliente.

Descoberta pelo API Hub e pelo Agent Registry

Se você integrar seu gateway ao hub de APIs, o gateway habilitado para MCP será publicado no hub de APIs como um servidor MCP com metadados adicionais específicos do MCP. Ele também vai aparecer automaticamente no Agent Registry.

Para gateways sem o MCP ativado, os metadados padrão da API são publicados. Somente os gateways com o MCP ativado vão mostrar essas configurações adicionais do MCP no Hub de API.

Não é necessário fazer outra etapa de registro. Os agentes podem descobrir o servidor e as ferramentas dele em qualquer um dos catálogos.

Para consultar o Agent Registry, ative a API dele no seu projeto:

gcloud services enable agentregistry.googleapis.com

A seguir