Servizio di accesso MCP API Merchant (alpha)

Utilizza il servizio di accesso Model Context Protocol (MCP) dell'API Merchant per ottenere l'accesso autorizzato ai dati e agli approfondimenti di Merchant Center per creare nuove esperienze agentiche e workflow automatizzati.

Panoramica

Il servizio di accesso MCP dell'API Merchant fornisce un bridge standardizzato e sicuro per LLM, agenti e assistenti al coding per creare e orchestrare nuove esperienze agentiche e workflow automatizzati basati sui dati di Merchant Center.

In particolare, consente l'accesso autorizzato ai dati di Merchant Center e ai report e agli approfondimenti generati da Google per eseguire operazioni di sola lettura e di scrittura limitata per gestire casi d'uso come:

• Diagnostica e risolvi i problemi di disapprovazione dei prodotti
• Generare report sul rendimento e approfondimenti
• Esamina l'attivazione dei miglioramenti automatici
• Crea e recupera origini dati

Controlli di sicurezza e controllo degli accessi

Il servizio di accesso MCP dell'API Merchant è progettato con una priorità sulla sicurezza:

• Autenticazione: l'esecuzione dello strumento è regolata dall'autenticazione standard dell'API Merchant, che richiede credenziali OAuth 2.0 o dell'account di servizio. Ti consigliamo di utilizzare credenziali con i diritti di accesso più restrittivi possibili.
• Sicurezza dell'esecuzione: sebbene la visibilità degli strumenti non sia limitata per il discovery degli agenti, l'esecuzione degli strumenti è limitata alle tue credenziali API specifiche.
• Misure di sicurezza: gli strumenti sono rigorosamente limitati alle operazioni di sola lettura e agli strumenti di scrittura a basso rischio (ad esempio, la creazione di origini dati) come misura di sicurezza.

Considerazioni importanti

Il servizio di accesso MCP dell'API Merchant è una versione alpha; il suo ambito e le sue funzionalità verranno ampliati e potrebbero cambiare.

Prima di iniziare, esamina le seguenti limitazioni e best practice:

Modifiche e release

Le modifiche possono avvenire senza preavviso e verranno pubblicate nelle note di rilascio.

Test sicuri

Ti consigliamo di fare prima degli esperimenti utilizzando un account di prova o un account non attivo prima di utilizzare questi strumenti in un ambiente di produzione attivo.

Quota condivisa

Il servizio di accesso MCP dell'API Merchant condivide lo stesso pool di quote delle chiamate API Merchant standard. L'esecuzione degli agenti può esaurire rapidamente la quota, soprattutto per i recuperi delle origini dati. Ti consigliamo vivamente di utilizzare un account di test per evitare interruzioni del servizio di produzione.

Filtro e sicurezza degli strumenti

In futuro verranno aggiunte nuove funzionalità, in particolare le azioni di scrittura. Ti consigliamo vivamente di configurare esplicitamente il client per il filtro degli strumenti integrati anziché esporre l'intero set di strumenti.

Riepilogo delle funzionalità disponibili

Puoi utilizzare il servizio di accesso MCP dell'API Merchant per eseguire le seguenti azioni in modo agentico:

• Recupera lo stato dettagliato e il contesto dei report per prodotti specifici utilizzando i nomi esatti delle risorse.
• Elenca e cerca più prodotti.
• Esegui query su metriche sul rendimento, stati dei prodotti e approfondimenti su prodotti più apprezzati, insight sul prezzo, scenario competitivo e dati e analisi del programma di affiliazione di YouTube Shopping.
• Identifica i problemi a livello di account che influiscono sulla visibilità dei prodotti o sulla partecipazione al programma.
• Elenca, crea, recupera e controlla lo stato di caricamento delle origini dati.
• Elenca i motivi aggregati delle disapprovazioni dei prodotti nel tuo inventario.
• Esamina le impostazioni di miglioramento automatico per articoli, immagini e spedizione.
• Controlla le regioni attive, i requisiti non soddisfatti e lo stato di partecipazione per programmi Merchant Center specifici.

Per iniziare

Per connettere l'IDE, l'assistente al coding o l'agente al servizio di accesso MCP dell'API Merchant, aggiorna le impostazioni del client MCP (ad esempio mcp.json o settings.json).

Configurazione client

Configurazioni:

{
    "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}"
      }
    }
  }'

Scenari di utilizzo di esempio

Per illustrare come puoi sfruttare il servizio di accesso MCP dell'API Merchant per creare esperienze agentiche e workflow automatizzati, considera i seguenti scenari:

Scenario 1: diagnostica e correggi le disapprovazioni dei prodotti

Vuoi capire perché un prodotto specifico non viene visualizzato nei risultati di ricerca di Google.

Prompt dell'utente:

"Perché il mio prodotto con ID offerta 'offer123' non è stato approvato?"

Comportamento dell'agente con MCP:

1. L'agente chiama list_products o get_product_by_name per individuare lo stato del prodotto.
2. Il server MCP restituisce lo stato del prodotto, incluso un elenco di issues (ad esempio, "Formato del prezzo errato" o "Valore di spedizione mancante").
3. L'agente analizza i problemi e ti spiega la causa principale, suggerendoti come risolvere il problema (ad esempio, aggiornando le informazioni sul prezzo).

Scenario 2: esamina l'attivazione dei miglioramenti automatici

Vuoi verificare se i miglioramenti automatici della spedizione sono attivi.

Prompt dell'utente:

"I miglioramenti automatici della spedizione sono attivi?"

Comportamento dell'agente con MCP:

1. L'agente chiama get_automatic_improvements per recuperare le impostazioni a livello di account.
2. Il server MCP restituisce la configurazione che mostra lo stato dei miglioramenti delle immagini, degli articoli e della spedizione.
3. L'agente conferma che i miglioramenti della spedizione sono attivi o spiega come attivarli se sono disattivati.

Scenario 3: genera report sul rendimento e insight

Vuoi controllare rapidamente il tuo rendimento recente senza navigare nell'interfaccia utente di Merchant Center.

Prompt dell'utente:

"Mostrami i miei 5 prodotti con il rendimento migliore in base ai clic della settimana scorsa."

Comportamento dell'agente con MCP:

1. L'agente crea una query MCQL (Merchant Center Query Language) che ha come target la tabella product_performance_view, ordinata per clicks DESC e limitata a 5.
2. L'agente chiama report_search con la query creata.
3. Il server MCP esegue la query sul database dei report in tempo reale e restituisce le righe.
4. L'agente formatta i risultati in una tabella Markdown chiara.

Scenario 4: crea e recupera le origini dati

Vuoi aggiungere una nuova origine dati per caricare gli aggiornamenti dei prodotti.

Prompt dell'utente:

"Crea un'origine dati supplementare denominata 'aggiornamenti-prezzi' per il mio account commerciante."

Comportamento dell'agente con MCP:

1. L'agente chiama create_data_source con le impostazioni specificate per registrare il nuovo feed.
2. Il server MCP crea l'origine dati e restituisce il nome della risorsa univoco.
3. L'agente chiama fetch_data_source per attivare il download e l'elaborazione del file associato.
4. L'agente chiama get_file_upload per monitorare l'avanzamento del caricamento e confermare lo stato di elaborazione riuscita degli elementi.

Strumenti MCP e descrizioni

Il servizio di accesso MCP dell'API Merchant espone i seguenti strumenti al tuo agente: