O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Configurar o Protocolo de Contexto de Modelo

Neste documento, descrevemos 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 a OpenAPI 2.0.
Entenda os conceitos básicos do gateway de API.

Validação de configuração

Quando você faz 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). As operações sem uma descrição resolúvel são rejeitadas.
Segurança: se você configurar a autenticação para tools/list, será necessário nomear exatamente um esquema de segurança definido em components.securitySchemes. O esquema pode ser um esquema JWT ou um esquema de chave de API. Se você usar um esquema JWT, também precisará nomeá-lo no requisito security de nível superior da especificação.

Modelo de autenticação

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

Ciclo de vida do protocolo: os métodos initialize e notifications/initialized não são autenticados.
Invocação de ferramenta (tools/call): reutiliza as políticas de autenticação definidas para a operação subjacente na sua especificação OpenAPI. Ele aplica 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, recomendamos que você proteja a descoberta de ferramentas ativando a autenticação para esse método usando tools-list.security. É possível autenticar o tools/list com um JWT ou uma chave de API.

Etapas para configurar o MCP

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

1. Identificar operações para expor

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 configurá-lo para cada operação.

Capacitação global

Ative o MCP globalmente adicionando 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

Quando ativadas globalmente, todas as operações qualificadas (com base no método e no 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 modificar as configurações globais ou expor operações de maneira seletiva 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."

Também é possível 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, recomendamos que você aplique a autenticação configurando tools-list.security em x-google-api-management.mcp. É possível nomear um esquema JWT ou um esquema de chave de API.

O exemplo a seguir requer um JWT:

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

O exemplo a seguir requer uma chave de API. Os clientes precisam enviar a chave no cabeçalho HTTP x-api-key. O tools/list não lê chaves de API de parâmetros de consulta. Uma solicitação sem uma chave válida recebe um erro JSON-RPC e nenhuma lista de ferramentas. Para saber como criar uma chave de API, consulte Usar chaves de API.

x-google-api-management:
  mcp:
    tools-list:
      security:
        api_key: []
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header

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

Crie uma configuração de API com base na especificação anotada e implante-a em um gateway usando o fluxo padrão. Consulte Como implantar uma API em um gateway para mais detalhes. Para mudar as ferramentas mais tarde, consulte Atualizar as ferramentas do MCP expostas.

5. Verificar o suporte ao MCP

Depois de implantado, verifique se o gateway está atendendo às solicitações do MCP.

Handshake

Envie uma solicitação de inicialização para estabelecer a versão e os recursos 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"}
  }
}'

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. Se você configurou tools-list.security, adicione a credencial correspondente, como um cabeçalho Authorization: Bearer para um JWT ou um cabeçalho x-api-key para uma chave de API:

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 para uma ferramenta são mapeados para a solicitação REST com base na especificação da OpenAPI:

Parâmetros de caminho e consulta: tornam-se propriedades de nível superior no objeto arguments, com chave pelos nomes de parâmetro 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.

A solicitação de back-end transcodificada é indistinguível de uma solicitação REST direta para seu serviço de back-end. Os serviços de back-end não conseguem distinguir de forma programática entre uma chamada REST direta e uma transcodificada do MCP.

Invocar uma ferramenta

Invocar uma ferramenta específica. Inclua os tokens de autenticação necessários se a operação REST subjacente 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"}
  }
}'

Atualizar as ferramentas do MCP expostas

As configurações de API no gateway de API são imutáveis. Portanto, não é possível mudar a definição da API em uma configuração de API atual. Como resultado, a resposta tools/list é estática para cada configuração de API implantada.

Para adicionar, remover, renomear ou atualizar ferramentas MCP expostas ou configurações de segurança do tools/list, crie uma nova configuração de API e implante-a no gateway:

Atualize sua especificação da OpenAPI 3.x, incluindo operações, valores operationId, resumos, parâmetros e as extensões x-google-api-management.mcp e x-google-mcp-tool.
Crie uma configuração de API com um novo ID:
```
gcloud api-gateway api-configs create NEW_CONFIG_ID \
    --api=API_ID \
    --openapi-spec=API_DEFINITION \
    --project=PROJECT_ID \
    --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
```
Substitua:
- NEW_CONFIG_ID: um novo ID para a configuração atualizada da API.
- API_ID: o ID da API do gateway de API.
- API_DEFINITION: o caminho para a especificação OpenAPI 3.x atualizada.
- PROJECT_ID: o ID do projeto do Google Cloud .
- SERVICE_ACCOUNT_EMAIL: o endereço de e-mail da conta de serviço usada para assinar tokens para back-ends com autenticação configurada. Omita essa flag se nenhum dos back-ends exigir autenticação.
Para mais informações, consulte Criar uma configuração de API.
Atualize cada gateway que disponibiliza a API para usar a nova configuração:
```
gcloud api-gateway gateways update GATEWAY_ID \
    --api=API_ID \
    --api-config=NEW_CONFIG_ID \
    --location=GCP_REGION \
    --project=PROJECT_ID
```
Substitua:
- GATEWAY_ID: o ID do gateway a ser atualizado
- GCP_REGION: a região em que o gateway está implantado.
Para mais informações, consulte Atualizar um gateway.
Chame tools/list para verificar o conjunto de ferramentas atualizado. Para ver um exemplo de solicitação, consulte Descobrir ferramentas.
Depois que nenhum gateway usar a configuração de API anterior, exclua a configuração de API substituída:
```
gcloud api-gateway api-configs delete OLD_CONFIG_ID \
    --api=API_ID \
    --project=PROJECT_ID
```
Substitua OLD_CONFIG_ID pelo ID da configuração da API substituída. Não exclua uma configuração de API enquanto algum gateway ainda a estiver usando. Se a nova configuração de API renomear ou remover métricas de cota, os gateways que ainda usam uma configuração de API mais antiga poderão retornar erros HTTP 500 até serem atualizados (consulte As cotas se aplicam a toda a API). Para mais informações, consulte Excluir uma configuração de API.

Lembre-se dos seguintes comportamentos de lançamento e do cliente ao atualizar as ferramentas de MCP:

Lançamento sem inatividade: o gateway de API atualiza os gateways sem inatividade. Enquanto a nova configuração da API é propagada, algumas solicitações podem chegar brevemente à configuração anterior. Se a API estiver implantada em vários gateways ou regiões, atualize cada gateway separadamente.
Caches de ferramentas do cliente: como o gateway de API disponibiliza o MCP em um transporte HTTP sem estado, ele não emite notificações notifications/tools/list_changed. Depois que a atualização do gateway for concluída, os clientes do MCP que armazenam definições de ferramentas em cache precisarão chamar tools/list novamente para descobrir as ferramentas atualizadas.
Limites de configuração da API: cada API é limitada a 100 configurações. Portanto, exclua as configurações substituídas depois de atualizar os gateways. Crie as configurações de API uma por uma. Se você iniciar uma segunda configuração para a mesma API antes que a primeira seja concluída, uma ou ambas podem não ser utilizáveis por um gateway. Para mais informações, consulte Cotas e limites.

Observabilidade

As solicitações de MCP geram métricas e registros padrão do gateway de API. É possível distinguir o tráfego do MCP do tráfego REST padrão inspecionando o caminho da solicitação (que geralmente termina em /mcp) ou configurando métricas personalizadas.

Solução de 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 aplicativo, já que respostas que não são 200 podem fazer com que muitos clientes 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 de 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 não é compatível com o gateway.
Versão do protocolo ausente	`-32602`	`200`	Os parâmetros `initialize` omitem `protocolVersion` ou não são uma string.
Ferramenta desconhecida	`-32602`	`200`	O nome da ferramenta não foi encontrado na configuração da API implantada. Atualize o cache da ferramenta do cliente ou consulte Atualizar as ferramentas do MCP expostas.
Argumentos de ferramenta inválidos	`-32602`	`200`	Os argumentos estão ausentes ou são inválidos. Verifique o aninhamento de chaves `body`.
O corpo é muito longo	`-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 carrega um cabeçalho `WWW-Authenticate` que aponta para os metadados do recurso protegido.

Os erros do aplicativo 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.