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

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

Présentation

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

Plus précisément, elle 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 des opérations d'écriture limitées afin de répondre à des cas d'utilisation tels que :

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

Contrôles de sécurité et d'accès

Le service d'accès MCP de l'API Merchant est conçu en priorité pour 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é de l'exécution : bien que la visibilité des outils ne soit pas limitée pour la découverte agentive, 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 garde-fou de sécurité.

Remarques importantes

Le service d'accès MCP de l'API Merchant est une version alpha. Son champ d'application et ses fonctionnalités seront étendus et pourront être modifiés.

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

Modifications et versions

Des 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 à l'aide d'un compte de test ou d'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. L'exécution d'agents peut rapidement épuiser le quota, en particulier pour les récupérations de sources de données. Nous vous recommandons vivement d'utiliser un compte de test pour éviter toute interruption du service de production.

Filtrage des outils et sécurité

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

Résumé 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 agentive :

• Récupérez l'état détaillé et le contexte de reporting pour des produits spécifiques à l'aide de noms de ressources exacts.
• Lister et rechercher plusieurs produits.
• Interrogez les métriques de performances, l'état des produits et les insights sur les produits populaires, les tendances des prix, la visibilité par rapport aux concurrents et les données analytiques du programme d'affiliation 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 :

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

Exemples de scénarios d'utilisation

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

Scénario 1 : Identifier 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.

Prompt de l'utilisateur :

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

Comportement de l'agent avec le MCP :

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

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

Vous voulez vérifier si l'amélioration automatique de la livraison est activée.

Prompt de l'utilisateur :

"L'amélioration automatique de la livraison est-elle activée ?"

Comportement de l'agent avec le 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 la 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.

Prompt de l'utilisateur :

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

Comportement de l'agent avec le MCP :

1. L'agent crée une requête en langage de requête Merchant Center (MCQL) ciblant la table product_performance_view, en triant par clicks DESC et en 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 reporting en direct et renvoie les lignes.
4. L'agent met en forme les résultats dans un tableau Markdown clair.

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.

Prompt de l'utilisateur :

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

Comportement de l'agent avec le 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 que les éléments ont bien été traités.

Outils MCP et descriptions

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