Service d'accès MCP de l'API Merchant (alpha)

Utilisez le service d'accès MCP (Model Context Protocol) de la Merchant API pour obtenir un accès autorisé à vos données et insights Merchant Center. Vous pourrez ainsi créer de nouvelles expériences agentiques et de nouveaux workflows automatisés.

Présentation

Le service d'accès MCP à Merchant API fournit un pont standardisé et sécurisé pour que les LLM, les agents et les assistants de codage puissent créer et orchestrer de nouvelles expériences agentiques et des workflows automatisés basés sur les données Merchant Center.

Plus précisément, il permet un accès autorisé à vos données Merchant Center, ainsi qu'aux rapports et insights générés par Google, pour effectuer des opérations en lecture seule et en écriture limitée afin de répondre à des cas d'utilisation tels que :

  • Diagnostiquer et corriger les refus de produits
  • Générer des rapports et des insights sur les performances
  • Examiner l'activation des améliorations automatiques
  • Créer et récupérer des sources de données

Sécurité et contrôles d'accès

Le service d'accès MCP de l'API Merchant a été conçu en privilégiant la sécurité :

  • Authentification : l'exécution de l'outil est régie par l'authentification standard de l'API Merchant, qui nécessite des identifiants OAuth 2.0 ou de compte de service. Nous vous recommandons d'utiliser des identifiants avec les droits d'accès les plus restrictifs possible.
  • Sécurité d'exécution : bien que la visibilité des outils ne soit pas limitée pour la découverte agentique, l'exécution des outils est limitée à vos identifiants API spécifiques.
  • Mesures de protection : les outils sont strictement limités aux opérations en lecture seule et aux outils d'écriture à faible risque (par exemple, la création de sources de données) en tant que mesure de protection.

Remarques importantes

Le service d'accès MCP de l'API Merchant est une version alpha. Sa portée et ses fonctionnalités seront étendues et peuvent changer.

Avant de commencer, consultez les limites et les bonnes pratiques suivantes :

Modifications et versions

Les modifications peuvent être apportées sans préavis et seront publiées dans les notes de version.

Tests sécurisés

Nous vous recommandons de commencer par faire des tests avec un compte de test ou un compte non actif avant d'utiliser ces outils dans un environnement de production actif.

Quota partagé

Le service d'accès MCP de l'API Merchant partage le même pool de quotas que vos appels standards à l'API Merchant. Les agents en cours d'exécution peuvent rapidement épuiser le quota, en particulier pour les extractions de sources de données. Nous vous recommandons vivement d'utiliser un compte de test pour éviter toute interruption de service en production.

Filtrage des outils et sécurité

De nouvelles fonctionnalités, en particulier les actions d'écriture, seront ajoutées à l'avenir. Nous vous recommandons vivement de configurer explicitement votre client pour le filtrage des outils intégrés plutôt que d'exposer l'ensemble de l'ensemble d'outils.

Récapitulatif des fonctionnalités disponibles

Vous pouvez utiliser le service d'accès MCP de l'API Merchant pour effectuer les actions suivantes de manière agentique :

  • Récupérez le contexte détaillé de l'état et des rapports pour des produits spécifiques à l'aide de noms de ressources exacts.
  • Lister et rechercher plusieurs produits
  • Requête : métriques de performance, états des produits et insights sur les produits populaires, insights sur les prix, visibilité par rapport aux concurrents et données analytiques sur les affiliés YouTube Shopping.
  • Identifiez les problèmes au niveau du compte qui affectent la visibilité des produits ou la participation au programme.
  • Lister, créer, récupérer et vérifier l'état d'importation des sources de données.
  • Lister les raisons agrégées des refus de produits dans votre inventaire.
  • Vérifiez les paramètres d'amélioration automatique pour les articles, les images et la livraison.
  • Vérifiez les régions actives, les exigences non satisfaites et l'état de participation pour des programmes Merchant Center spécifiques.

Premiers pas

Pour connecter votre IDE, votre assistant de codage ou votre agent au service d'accès MCP de l'API Merchant, mettez à jour les paramètres de votre client MCP (par exemple, mcp.json ou settings.json).

Configuration du client

Configurations :

Antigravity

Connectez-vous directement au point de terminaison MCP distant hébergé à l'aide d'un jeton d'accès OAuth 2.0 (avec le champ d'application https://www.googleapis.com/auth/content). Suivez les instructions de la documentation Antigravity.

{
    "mcpServers": {
        "merchant-api-access": {
            "serverUrl": "https://merchantapi.googleapis.com/mcp",
            "headers": {
                "Authorization": "Bearer {ACCESS_TOKEN}",
                "x-goog-user-project": "{GOOGLE_CLOUD_PROJECT_ID}"
            }
        }
    }
}

Claude CLI

Ajoutez le point de terminaison MCP distant hébergé directement dans Claude CLI à l'aide de la commande claude mcp add :

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

Suivez les instructions de la documentation Claude MCP.

cURL

Envoyez des requêtes JSON-RPC 2.0 standards directement au point de terminaison MCP de l'API Merchant hébergée.

Lister les outils disponibles :

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

Exécutez un appel d'outil (par exemple, list_data_sources) :

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

Remplacez les éléments suivants :

  • ACCOUNT_ID : votre ID Merchant Center
  • ACCESS_TOKEN : jeton d'autorisation pour effectuer l'appel d'API
  • GOOGLE_CLOUD_PROJECT_ID : ID du projet Google Cloud associé à votre compte Merchant Center

Exemples de scénarios d'utilisation

Pour illustrer comment vous pouvez utiliser le service d'accès MCP à Merchant API pour créer des expériences agentiques et des workflows automatisés, considérez les scénarios suivants :

Scénario 1 : Diagnostiquer et corriger les refus de produits

Vous souhaitez comprendre pourquoi un produit spécifique n'apparaît pas dans les résultats de recherche Google.

Requête utilisateur :

"Pourquoi mon produit avec l'ID d'offre 'offer123' a-t-il été refusé ?"

Comportement de l'agent avec MCP :

  1. L'agent appelle list_products ou get_product_by_name pour connaître l'état du produit.
  2. Le serveur MCP renvoie l'état du produit, y compris une liste de issues (par exemple, "Format du prix incorrect" ou "Valeur de livraison manquante").
  3. L'agent analyse les problèmes et vous explique leur cause première, en vous suggérant comment les résoudre (par exemple, en mettant à jour les informations sur les prix).

Scénario 2 : Examiner l'activation des améliorations automatiques

Vous souhaitez vérifier si vos améliorations automatiques de la livraison sont actives.

Requête utilisateur :

"Mes améliorations automatiques de la livraison sont-elles activées ?"

Comportement de l'agent avec MCP :

  1. L'agent appelle get_automatic_improvements pour récupérer les paramètres au niveau du compte.
  2. Le serveur MCP renvoie la configuration indiquant l'état des améliorations apportées aux images, aux articles et à la livraison.
  3. L'agent confirme que les améliorations de livraison sont actives ou explique comment les activer si elles sont désactivées.

Scénario 3 : Générer des rapports et des insights sur les performances

Vous souhaitez vérifier rapidement vos performances récentes sans parcourir l'interface utilisateur de Merchant Center.

Requête utilisateur :

"Affiche mes cinq produits les plus performants en termes de clics la semaine dernière."

Comportement de l'agent avec MCP :

  1. L'agent construit une requête MCQL (Merchant Center Query Language) ciblant la table product_performance_view, en l'ordonnant par clicks DESC et en la limitant à 5.
  2. L'agent appelle report_search avec la requête construite.
  3. Le serveur MCP exécute la requête sur la base de données de rapports en direct et renvoie les lignes.
  4. L'agent met en forme les résultats dans un tableau Markdown clair pour vous.

Scénario 4 : Créer et récupérer des sources de données

Vous souhaitez ajouter une source de données pour importer des mises à jour de produits.

Requête utilisateur :

"Crée une source de données supplémentaire nommée 'price-updates' pour mon compte marchand."

Comportement de l'agent avec MCP :

  1. L'agent appelle create_data_source avec les paramètres spécifiés pour enregistrer le nouveau flux.
  2. Le serveur MCP crée la source de données et renvoie son nom de ressource unique.
  3. L'agent appelle fetch_data_source pour déclencher le téléchargement et le traitement du fichier associé.
  4. L'agent appelle get_file_upload pour surveiller la progression de l'importation et confirmer l'état de traitement réussi des éléments.

Outils et descriptions MCP

Le service d'accès MCP à Merchant API expose les outils suivants à votre agent :

Outil MCP Description
get_product_by_name Obtenez des informations sur un produit pour un marchand donné en utilisant le nom exact de la ressource produit. Renvoie l'état détaillé du produit, qui contient le contexte des rapports et les problèmes potentiels au niveau du produit.
list_products Lister ou rechercher plusieurs produits pour un marchand donné Renvoie l'état détaillé du produit, qui contient le contexte de rapport et les problèmes potentiels au niveau du produit pour plusieurs produits.
report_search Interrogez les tableaux de rapports pour récupérer les métriques de performances des produits, leur état, les tendances sur les prix et la visibilité par rapport aux concurrents. Pour en savoir plus, consultez le guide sur les rapports.
list_data_sources Liste les sources de données disponibles pour un marchand donné.
get_data_source Obtenez les détails d'une source de données spécifique.
create_data_source Créez une source de données pour un marchand donné.
fetch_data_source Récupérer et traiter le fichier associé à une source de données pour un marchand donné.
get_file_upload Obtenez l'état du dernier fichier importé pour une source de données donnée.
list_accounts Lister les comptes d'un utilisateur donné.
list_account_issues Lister les problèmes au niveau du compte pour un marchand donné afin d'identifier les problèmes qui affectent l'ensemble du compte.
list_programs Lister les programmes pour un marchand donné, y compris l'état de participation, les régions actives et les exigences non satisfaites.
list_aggregate_product_statuses Affichez la liste des problèmes agrégés au niveau du produit pour surveiller l'état général de vos données produit.
get_automatic_improvements Accédez aux paramètres d'améliorations automatiques, y compris les mises à jour des articles, les améliorations des images et les améliorations de la livraison.