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 orquestrarem novas experiências agênticas e fluxos de trabalho automatizados com base nos dados do Merchant Center.

Especificamente, ele 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 resolver casos de uso como:

• Diagnosticar e corrigir reprovações de produtos
• Gerar relatórios e insights de performance
• Revisar 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 usar credenciais com os direitos de acesso mais restritivos possíveis.
• Segurança de execução: embora a visibilidade das ferramentas não seja restrita para a descoberta de agentes, a execução delas é 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 fonte de dados) como uma proteção de segurança.

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 ampliados e podem mudar.

Antes de começar, leia as limitações e práticas recomendadas a seguir:

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 testar 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 ao MCP da API Merchant compartilha o mesmo pool de cotas das chamadas padrão da API Merchant. A execução de agentes pode esgotar rapidamente a cota, principalmente para busca de fontes de dados. Recomendamos usar uma conta de teste para evitar interrupções no serviço de produção.

Filtragem e segurança de ferramentas

Novas funcionalidades, principalmente ações de gravação, serão adicionadas no futuro. Recomendamos configurar explicitamente o cliente para filtragem de ferramentas integrada 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:

• Recupere o contexto detalhado de status e relatórios para produtos específicos usando nomes de recursos exatos.
• Listar e pesquisar vários produtos.
• Consultar métricas de performance, status de produtos e insights sobre produtos populares, informações de preço, visibilidade competitiva e análises de afiliados do YouTube Shopping.
• Identifique 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.
• Liste os motivos agregados para reprovações de produtos em todo o inventário.
• Analise 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 ao 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}" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

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}" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_data_sources",
      "arguments": {
        "parent": "accounts/{ACCOUNT_ID}"
      }
    }
  }'

Substitua:

• ACCOUNT_ID: seu ID do Merchant Center
• ACCESS_TOKEN: o token de autorização para fazer a chamada de API.
• GOOGLE_CLOUD_PROJECT_ID: o ID do projeto do Google Cloud associado à sua conta do Merchant Center

Exemplos de cenários de uso

Para ilustrar como você pode aproveitar 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 chama 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 corrigir (por exemplo, atualizando as informações de preço).

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

Você quer verificar se a otimização automática de envio está ativa.

Comando do usuário:

Minhas 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 que as melhorias no frete estão ativas ou explica como ativá-las se estiverem desativadas.

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

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) direcionada à 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: