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 ponte standardizzato e sicuro per LLM, agenti e assistenti alla programmazione 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 scrittura limitata per risolvere casi d'uso come:

• Diagnosi e correzione delle mancate approvazioni dei prodotti
• Generazione di report sul rendimento e approfondimenti
• Revisione dell'attivazione dei miglioramenti automatici
• Creazione e recupero delle origini dati

Controlli di accesso e sicurezza

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

• Autenticazione: l'esecuzione dello strumento è regolata dall'autenticazione standard dell'API Merchant, che richiede le credenziali OAuth 2.0 o del service account. Ti consigliamo di utilizzare le credenziali con i diritti di accesso più restrittivi possibili.
• Sicurezza di esecuzione: sebbene la visibilità degli strumenti non sia limitata per il rilevamento agentico, l'esecuzione degli strumenti è limitata alle tue credenziali API specifiche.
• Misure di salvaguardia: per motivi 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).

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 essere apportate senza preavviso e verranno pubblicate nelle note di rilascio.

Test sicuri

Ti consigliamo di sperimentare prima utilizzando un account di test o un account non live prima di utilizzare questi strumenti in un ambiente di produzione live.

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 integrato 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 delle risorse esatti.
• Elenca e cerca più prodotti.
• Esegui query sulle metriche sul rendimento, sugli stati dei prodotti e sugli approfondimenti relativi a prodotti più apprezzati, insight sul prezzo, scenario competitivo e dati e analisi degli affiliati 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 mancate approvazioni dei prodotti nell'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 alla programmazione 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}" \
  -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}"
      }
    }
  }'

Sostituisci quanto segue:

• ACCOUNT_ID: il tuo ID Merchant Center
• ACCESS_TOKEN: il token di autorizzazione per effettuare la chiamata API
• GOOGLE_CLOUD_PROJECT_ID: l'ID del progetto Google Cloud associato al tuo account Merchant Center

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, prendi in considerazione i seguenti scenari:

Scenario 1: diagnosi e correzione delle mancate approvazioni dei prodotti

Vuoi capire perché un prodotto specifico non viene visualizzato nei risultati della Ricerca Google.

Prompt utente:

"Perché il mio prodotto con l'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, inclusa una lista 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 risolverla (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 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 di immagini, articoli e 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 approfondimenti

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

Prompt utente:

"Mostrami i 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, ordinando per clicks DESC e limitando a 5.
2. L'agente chiama report_search con la query creata.
3. Il server MCP esegue la query sul database dei report live e restituisce le righe.
4. L'agente formatta i risultati in una tabella Markdown chiara per te.

Scenario 4: crea e recupera le origini dati

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

Prompt utente:

"Crea un'origine dati supplementare denominata 'price-updates' 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 relativo 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 articoli.

Strumenti MCP e descrizioni

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