Configurar o Protocolo de Contexto de Modelo

Prévia

Esse recurso está sujeito aos "Termos das ofertas pré-GA" na seção "Termos gerais de serviço" dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Este documento descreve como configurar o gateway de API para atuar como um servidor remoto do Protocolo de Contexto de Modelo (MCP).

Antes de começar

• Verifique se você tem uma especificação OpenAPI 3.x válida para sua API. O MCP não é compatível com o OpenAPI 2.0.
• Entenda os fundamentos do gateway de API.

Validação de configuração

Ao fazer upload da especificação OpenAPI, o gateway de API realiza as seguintes validações para a configuração do MCP:

• Local: a extensão x-google-mcp-tool só pode ser especificada no nível da operação individual.
• Método HTTP: somente as operações GET, POST, PUT, PATCH e DELETE podem ser expostas como ferramentas do MCP.
• Nome da ferramenta: os nomes das ferramentas precisam corresponder a [A-Za-z0-9_.-]{1,128} e ser exclusivos em toda a especificação.
• Descrição: cada ferramenta precisa ter uma descrição não vazia (extraída da descrição, do resumo ou da substituição da operação). Operações sem uma descrição resolvida são rejeitadas.
• Segurança: se você configurar a autenticação para tools/list, nomeie exatamente um esquema de segurança JWT definido em components.securitySchemes. A segurança da chave de API não é compatível com tools/list na Visualização pública.

Modelo de autenticação

O gateway de API aplica regras de autenticação diferentes dependendo do método MCP chamado:

• Ciclo de vida do protocolo: os métodos initialize e notifications/initialized são não autenticados.
• Invocação de ferramenta (tools/call): reutiliza as políticas de autenticação definidas para a operação subjacente na especificação OpenAPI. Ele impõe os mesmos requisitos de chave de API ou JWT que a chamada direta do endpoint REST.
• Descoberta de ferramentas (tools/list): por padrão, esse método não é autenticado. No entanto, como prática recomendada de segurança, é altamente recomendável proteger a descoberta de ferramentas ativando a autenticação para esse método usando tools-list.security. Se você ativar a autenticação, use um esquema de segurança JWT. A autenticação de chave de API não é compatível com tools/list.

Etapas para configurar o MCP

Siga estas etapas para expor sua API como ferramentas do MCP:

1. Identificar operações a serem expostas

Revise sua especificação OpenAPI e decida quais operações devem estar disponíveis para os agentes de IA.

2. Atualizar a especificação OpenAPI

É possível ativar o MCP globalmente para todas as operações qualificadas ou configurar por operação.

Ativação global

Para ativar o MCP globalmente, adicione o campo mcp a x-google-api-management no nível do documento:

openapi: 3.0.3
info:
  title: Bookstore API
  version: 1.0.0
x-google-api-management:
  mcp: true
  backends:
    bookstore-backend:
      address: https://bookstore-backend-12345678.us-central1.run.app

Observação: verifique se as operações têm um back-end configurado (usando x-google-backend no nível da operação ou padrões globais) para serem qualificadas como ferramentas do MCP.

Quando ativadas globalmente, todas as operações qualificadas (com base no método e caminho HTTP) são expostas como ferramentas do MCP. Por padrão, o nome da ferramenta é o operationId da operação, e a descrição é a descrição ou o resumo da operação.

Configuração por operação

É possível substituir as configurações globais ou expor operações seletivamente usando x-google-mcp-tool:

paths:
  /v1/shelves/{shelf}:
    delete:
      operationId: deleteShelf
      summary: Delete a shelf.
      x-google-backend: bookstore-backend
      x-google-mcp-tool:
        name: delete_shelf
        description: "Permanently delete a shelf and every book on it."

Você também pode desativar uma operação quando ela estiver ativada globalmente definindo x-google-mcp-tool: false.

3. Autenticar tools/list (recomendado)

Por padrão, o método tools/list (que enumera as ferramentas disponíveis) não é autenticado. Como prática recomendada de segurança, é altamente recomendável configurar a autenticação em tools-list.security, em x-google-api-management/mcp. Você precisa usar um esquema JWT. As chaves de API não são compatíveis com esse método.

x-google-api-management:
  mcp:
    tools-list:
      security:
        myJWT: []

Observação: configurar a extensão mcp como um objeto (por exemplo, para ativar a autenticação do tools/list) também ativa o MCP globalmente para todas as operações qualificadas. Se você quiser configurar a segurança do tools/list, mas não quiser expor todas as operações qualificadas, desative explicitamente essas operações definindo x-google-mcp-tool: false.

4. Criar e implantar a configuração de API

Crie uma configuração de API com base na especificação anotada e implante-a em um gateway usando o fluxo padrão. Para mais detalhes, consulte Como implantar uma API em um gateway.

5. Verificar o suporte do MCP

Depois da implantação, você pode verificar se o gateway está atendendo às solicitações do MCP.

Handshake

Envie uma solicitação de inicialização para estabelecer a versão e as capabilities do protocolo:

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {"name": "demo-client", "version": "1.0.0"}
  }
}'

Observação: os clientes precisam enviar o cabeçalho MCP-Protocol-Version em todas as solicitações após a inicialização. Se o cabeçalho estiver ausente, o gateway vai voltar para a versão 2025-03-26.

Confirmar handshake

Confirme a inicialização. O gateway responde com HTTP 202 Accepted:

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}'

descobrem as ferramentas

Liste as ferramentas disponíveis:

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

Como os argumentos são mapeados para a solicitação REST

Os argumentos transmitidos a uma ferramenta são mapeados para a solicitação REST subjacente com base na especificação OpenAPI:

• Parâmetros de caminho e consulta: se tornam propriedades de nível superior no objeto arguments, com chave pelos nomes de parâmetros da OpenAPI.
• Corpo da solicitação: aninhado em uma única propriedade chamada body. Por exemplo, para criar um recurso, transmita {"body": {"fieldName": "value"}}.
• Cabeçalhos: também se tornam propriedades de nível superior. O gateway os injeta como cabeçalhos HTTP padrão na chamada de back-end.

Observação: não é possível vincular parâmetros a cabeçalhos de sistema reservados ou cabeçalhos que começam com x-google-.

A solicitação de back-end transcodificada é indistinguível de uma solicitação REST direta ao seu serviço de back-end. Os serviços de back-end não podem distinguir programaticamente entre uma chamada REST direta e uma transcodificada do MCP.

Invocar uma ferramenta

Invocar uma ferramenta específica. Inclua todos os tokens de autenticação necessários se a operação REST subjacente os exigir:

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "delete_shelf",
    "arguments": {"shelf": "sci-fi"}
  }
}'

Observabilidade

As solicitações do MCP geram métricas e registros padrão do gateway de API. Para distinguir o tráfego do MCP do tráfego REST padrão, inspecione o caminho da solicitação (normalmente terminando em /mcp) ou configure métricas personalizadas.

Como solucionar problemas de falhas do MCP

O MCP distingue entre falhas de transporte e de protocolo. O gateway retorna HTTP 200 com um objeto de erro JSON-RPC para erros de protocolo e de aplicativo, já que respostas diferentes de 200 podem fazer com que muitos clientes do MCP falhem na camada de transporte.

A tabela a seguir descreve sintomas e correções comuns:

Sintoma	Código JSON-RPC	Status do HTTP	Significado e correção típica
Método não permitido	n/a	405	Uma solicitação que não é POST chegou a /mcp. Somente HTTP POST é aceito.
Erro de análise JSON	-32700	400	O corpo da solicitação não é um JSON válido.
Método ou ID ausente/inválido	-32600	200	O corpo é um JSON válido, mas não uma solicitação JSON-RPC válida. Verifique os campos obrigatórios (jsonrpc, method, id).
O método não é compatível	-32601	200	O método está fora do escopo compatível (por exemplo, ping).
Versão do protocolo sem suporte	-32602	200	O protocolVersion nomeia uma versão que o gateway não aceita.
Versão do protocolo ausente	-32602	200	Os parâmetros initialize omitem protocolVersion ou não é uma string.
Ferramenta desconhecida	-32602	200	O nome da ferramenta não foi encontrado. Limpe o cache do cliente ou verifique a implantação.
Argumentos de ferramenta inválidos	-32602	200	Os argumentos estão ausentes ou são inválidos. Verifique o aninhamento da chave body.
Corpo muito grande	-32000	200	O payload da resposta excedeu os limites de tamanho.
O corpo do transporte é muito grande	n/a	413	O corpo da solicitação HTTP bruta excedeu os limites de transporte do gateway.
Erro no servidor	-32000	200	Resposta do back-end não analisável. Verifique os registros.
Não autorizado / Proibido	n/a	401 / 403	Falha na autenticação. A resposta tem um cabeçalho WWW-Authenticate que aponta para metadados de recursos protegidos.

Os erros de aplicativos de back-end geralmente aparecem como uma resposta JSON-RPC bem-sucedida (HTTP 200) com result.isError: true contendo o corpo do erro de back-end.

A seguir

• Visão geral do Protocolo de Contexto de Modelo
• Extensões da OpenAPI 3.x
• Limitações de recursos do OpenAPI 3.x