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 de conta de serviço. Recomendamos usar 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 descoberta de agentes, 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 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 as capacidades serão ampliados 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ê teste 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 que as chamadas padrão da API Merchant. Agentes em execução podem 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

Novos recursos, principalmente ações de gravação, serão adicionados 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 autônoma:

• Recupere o status detalhado e o contexto de relatórios de 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, preços, visibilidade da concorrência 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 de 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, atualize o arquivo mcp.json para o Google Agent Studio, o Claude Desktop, o Antigravity, o Visual Studio Code ou sua estrutura de agente personalizada.

A configuração do serviço de acesso ao MCP da API Merchant local requer uma conta de serviço. O OAuth de usuário padrão não é compatível com essa execução local sem interface. Você precisa criar uma conta de serviço, fazer o download do arquivo JSON da chave privada e fornecer o caminho para ele junto com seu ID específico do Merchant Center como argumentos.

Para instruções detalhadas sobre como criar e fazer o download de uma conta de serviço, consulte o guia de contas de serviço.

Configuração do cliente

Configurações:

{
    "mcpServers": {
        "merchant-data-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@google/merchant-data-mcp",
                "--credentials",
                "/path/to/your/service-account-file.json"
            ]
        }
    }
}

{
    "mcpServers": {
        "merchant-data-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@google/merchant-data-mcp",
                "--credentials",
                "/path/to/your/service-account-file.json"
            ]
        }
    }
}

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 do 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 as melhorias automáticas de frete estão ativas.

Comando do usuário:

"As melhorias automáticas de frete 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 do 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 do 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: