Serviço de acesso ao MCP da API Merchant (Alfa)

Use o serviço de acesso ao Protocolo de Contexto de Modelo (MCP) da API Merchant para ter acesso autorizado aos dados e insights do Merchant Center e criar novas experiências agênticas e fluxos de trabalho automatizados.

Visão geral

O serviço de acesso ao MCP da API Merchant oferece uma ponte padronizada e segura para LLMs, agentes e assistentes de programação criarem e organizarem novas experiências agênticas e fluxos de trabalho automatizados com base nos dados do Merchant Center.

Especificamente, ela permite o acesso autorizado aos seus dados do Merchant Center e aos relatórios e insights gerados pelo Google para realizar operações de leitura e gravação limitadas para abordar casos de uso como:

• Diagnosticar e corrigir reprovações de produtos
• Gerar relatórios de performance e insights
• Analisar a ativação das melhorias automáticas
• Criar e buscar fontes de dados

Controles de segurança e acesso

O serviço de acesso ao MCP da API Merchant foi projetado com foco na segurança:

• Autenticação: a execução da ferramenta é regida pela autenticação padrão da API Merchant, que exige credenciais do OAuth 2.0 ou da conta de serviço. Recomendamos o uso de credenciais com os direitos de acesso mais restritivos possíveis.
• Segurança de execução: embora a visibilidade da ferramenta não seja restrita para a descoberta agêntica, a execução da ferramenta é restrita às suas credenciais de API específicas.
• Proteções: as ferramentas são estritamente limitadas a operações somente leitura e ferramentas de gravação de baixo risco (por exemplo, criação de fontes de dados) como uma proteção.

Considerações importantes

O serviço de acesso ao MCP da API Merchant é uma versão Alfa. O escopo e os recursos dele serão expandidos e podem mudar.

Antes de começar, confira as seguintes limitações e práticas recomendadas:

Mudanças e lançamentos

As mudanças podem acontecer sem aviso prévio e serão publicadas nas notas da versão.

Teste seguro

Recomendamos que você faça testes primeiro usando uma conta de teste ou uma conta não ativa antes de usar essas ferramentas em um ambiente de produção ativo.

Cota compartilhada

O serviço de acesso MCP da API Merchant compartilha o mesmo pool de cotas que as chamadas de API Merchant padrão. A execução de agentes pode esgotar rapidamente a cota, especialmente para buscas de fontes de dados. Recomendamos o uso de uma conta de teste para evitar interrupções no serviço de produção.

Filtragem e segurança de ferramentas

Novos recursos, especialmente ações de gravação, serão adicionados no futuro. Recomendamos configurar explicitamente o cliente para filtragem de ferramentas integradas em vez de expor todo o conjunto de ferramentas.

Resumo dos recursos disponíveis

Você pode usar o serviço de acesso ao MCP da API Merchant para realizar as seguintes ações de maneira agêntica:

• Recuperar o status detalhado e o contexto de relatórios para produtos específicos usando nomes de recursos exatos.
• Listar e pesquisar vários produtos.
• Consulte métricas de performance, status de produtos e insights sobre produtos mais procurados, informações de preço, visibilidade competitiva e análises do Programa de Afiliados do YouTube Shopping.
• Identificar problemas no nível da conta que afetam a visibilidade do produto ou a participação no programa.
• Listar, criar, buscar e verificar o status de upload das fontes de dados.
• Listar os motivos agregados das reprovações de produtos no seu inventário.
• Revise as configurações de melhoria automática para itens, imagens e frete.
• Verifique as regiões ativas, os requisitos não atendidos e o estado de participação em programas específicos do Merchant Center.

Primeiros passos

Para conectar seu IDE, assistente de programação ou agente ao serviço de acesso MCP da API Merchant, atualize as configurações do cliente MCP (por exemplo, mcp.json ou settings.json).

Configuração do cliente

Configurações:

{
    "mcpServers": {
        "merchant-api-access": {
            "serverUrl": "https://merchantapi.googleapis.com/mcp",
            "headers": {
                "Authorization": "Bearer {ACCESS_TOKEN}",
                "x-goog-user-project": "{GOOGLE_CLOUD_PROJECT_ID}"
            }
        }
    }
}

claude mcp add --transport http merchant-api https://merchantapi.googleapis.com/mcp --scope local \
  --header "Authorization: Bearer {ACCESS_TOKEN}" \
  --header "X-Goog-User-Project: {GOOGLE_CLOUD_PROJECT_ID}"

curl -s -X POST "https://merchantapi.googleapis.com/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Goog-User-Project: {GOOGLE_CLOUD_PROJECT_ID}" \
  -H "MCP-Protocol-Version: {MCP_PROTOCOL_VERSION}" \
  -H "Mcp-Method: tools/list" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion":
          "{MCP_PROTOCOL_VERSION}"
      }
    }
  }'

curl -s -X POST "https://merchantapi.googleapis.com/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Goog-User-Project: {GOOGLE_CLOUD_PROJECT_ID}" \
  -H "MCP-Protocol-Version: {MCP_PROTOCOL_VERSION}" \
  -H "Mcp-Method: tools/call" \
  -H "Mcp-Name: list_data_sources" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_data_sources",
      "arguments": {
        "parent": "accounts/{ACCOUNT_ID}"
      },
      "_meta": {
        "io.modelcontextprotocol/protocolVersion":
          "{MCP_PROTOCOL_VERSION}"
      }
    }
  }'

Exemplos de cenários de uso

Para ilustrar como você pode usar o serviço de acesso ao MCP da API Merchant para criar experiências agênticas e fluxos de trabalho automatizados, considere os seguintes cenários:

Cenário 1: diagnosticar e corrigir reprovações de produtos

Você quer entender por que um produto específico não está aparecendo nos resultados da Pesquisa Google.

Comando do usuário:

"Por que meu produto com o ID da oferta 'offer123' foi reprovado?"

Comportamento do agente com o MCP:

1. O agente faz uma ligação agêntica list_products ou get_product_by_name para localizar o status do produto.
2. O servidor MCP retorna o status do produto, incluindo uma lista de issues (por exemplo, "Formato de preço incorreto" ou "Valor de frete ausente").
3. O agente analisa os problemas e explica a causa raiz, sugerindo como corrigi-los (por exemplo, atualizando as informações de preço).

Cenário 2: revisar a ativação das melhorias automáticas

Você quer verificar se as otimizações automáticas de envio estão ativas.

Comando do usuário:

"As otimizações automáticas de envio estão ativadas?"

Comportamento do agente com o MCP:

1. O agente chama get_automatic_improvements para recuperar as configurações no nível da conta.
2. O servidor MCP retorna a configuração mostrando o status das melhorias de imagem, item e frete.
3. O agente confirma se as melhorias de frete estão ativas ou explica como ativá-las, se estiverem desativadas.

Cenário 3: gerar relatórios e insights de performance

Você quer verificar rapidamente sua performance recente sem navegar pela interface do Merchant Center.

Comando do usuário:

"Mostre meus cinco produtos com melhor performance por cliques na semana passada."

Comportamento do agente com o MCP:

1. O agente cria uma consulta da Linguagem de consulta do Merchant Center (MCQL) visando a tabela product_performance_view, ordenando por clicks DESC e limitando a 5.
2. O agente chama report_search com a consulta criada.
3. O servidor MCP executa a consulta no banco de dados de relatórios ativos e retorna as linhas.
4. O agente formata os resultados em uma tabela Markdown limpa para você.

Cenário 4: criar e buscar fontes de dados

Você quer adicionar uma nova fonte de dados para fazer upload de atualizações de produtos.

Comando do usuário:

"Crie uma fonte de dados complementar chamada 'price-updates' para minha conta do comerciante."

Comportamento do agente com o MCP:

1. O agente chama create_data_source com as configurações especificadas para registrar o novo feed.
2. O servidor MCP cria a fonte de dados e retorna o nome exclusivo do recurso.
3. O agente chama fetch_data_source para acionar o download e o processamento do arquivo associado.
4. O agente chama get_file_upload para monitorar o progresso do upload e confirmar o status de processamento bem-sucedido dos itens.

Ferramentas e descrições do MCP

O serviço de acesso ao MCP da API Merchant expõe as seguintes ferramentas ao seu agente: