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

Use o serviço de acesso do 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 do 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 acesso autorizado aos dados do Merchant Center e aos relatórios e insights gerados pelo Google para realizar operações de leitura e gravação limitadas para atender casos de uso como:

• Diagnosticar e corrigir reprovações de produtos
• Gerar relatórios de desempenho 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 do MCP da API Merchant foi projetado com prioridade 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.
• Salvaguardas: 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 de segurança.

Considerações importantes

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

Antes de começar, analise 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.

Testes seguros

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 do MCP da API Merchant compartilha o mesmo pool de cotas que as chamadas padrão da API Merchant. 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 seu cliente para a 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 do MCP da API Merchant para realizar as seguintes ações de maneira agêntica:

• Recuperar 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 desempenho, status de produtos e insights sobre produtos populares, insights de preços, 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.
• Analisar as configurações de melhoria automática de itens, imagens e frete.
• Verificar 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 do MCP da API Merchant, atualize as configurações do cliente do MCP. Por exemplo, atualize o arquivo mcp.json do Google Agent Studio, Claude Desktop, Antigravity, Visual Studio Code ou sua estrutura de agente personalizada.

A configuração do serviço de acesso do MCP da API Merchant local exige 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 de chave privada JSON 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 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 do 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 aparece 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 para você, sugerindo como corrigir o problema (por exemplo, atualizando as informações de preço).

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

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

Comando do usuário:

A otimização automática de envio está ativada?

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 de frete estão ativas ou explica como ativá-las se estiverem desativadas.

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

Você quer verificar rapidamente seu desempenho recente sem navegar na interface do Merchant Center.

Comando do usuário:

"Mostre meus cinco produtos com melhor desempenho 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, na sigla em inglês) 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 do recurso exclusivo.
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 do MCP da API Merchant expõe as seguintes ferramentas ao seu agente: