Servicio de acceso a MCP de la API de Merchant (alfa)

Usa el servicio de acceso al Protocolo de contexto del modelo (MCP) de la API de Merchant para obtener acceso autorizado a tus datos y estadísticas de Merchant Center, y así crear nuevas experiencias basadas en agentes y flujos de trabajo automatizados.

Descripción general

El servicio de acceso a MCP de la API de Merchant proporciona un puente seguro y estandarizado para que los LLM, los agentes y los asistentes de programación creen y coordinen nuevas experiencias basadas en agentes y flujos de trabajo automatizados basados en los datos de Merchant Center.

Específicamente, permite el acceso autorizado a tus datos de Merchant Center y a los informes y las estadísticas generados por Google para realizar operaciones de escritura limitadas y de solo lectura para abordar casos de uso como los siguientes:

  • Diagnostica y corrige los rechazos de productos
  • Generar informes y estadísticas de rendimiento
  • Revisa la habilitación de las mejoras automáticas
  • Cómo crear y recuperar fuentes de datos

Controles de seguridad y acceso

El servicio de acceso al MCP de la API de Merchant se diseñó con la seguridad como prioridad:

  • Autenticación: La ejecución de la herramienta se rige por la autenticación estándar de la API de Merchant, que requiere credenciales de OAuth 2.0 o de cuenta de servicio. Te recomendamos que uses credenciales con los derechos de acceso más restrictivos posibles.
  • Seguridad de ejecución: Si bien la visibilidad de la herramienta no está restringida para el descubrimiento de agentes, la ejecución de la herramienta está restringida a tus credenciales de API específicas.
  • Protecciones: Las herramientas se limitan estrictamente a operaciones de solo lectura y a herramientas de escritura de bajo riesgo (por ejemplo, la creación de fuentes de datos) como medida de seguridad.

Consideraciones importantes

El servicio de acceso al MCP de la API de Merchant es una versión alfa. Su alcance y sus capacidades se expandirán y pueden cambiar.

Antes de comenzar, revisa las siguientes limitaciones y prácticas recomendadas:

Cambios y lanzamientos

Los cambios pueden ocurrir sin previo aviso y se publicarán en las notas de la versión.

Pruebas seguras

Te recomendamos que primero experimentes con una cuenta de prueba o una cuenta que no sea en vivo antes de usar estas herramientas en un entorno de producción en vivo.

Cuota compartida

El servicio de acceso al MCP de la API de Merchant comparte el mismo grupo de cuotas que las llamadas estándar a la API de Merchant. Los agentes en ejecución pueden agotar rápidamente la cuota, en especial para las recuperaciones de fuentes de datos. Te recomendamos que uses una cuenta de prueba para evitar interrupciones en el servicio de producción.

Filtrado de herramientas y seguridad

En el futuro, se agregarán nuevas capacidades, en especial acciones de escritura. Te recomendamos que configures tu cliente de forma explícita para el filtrado de herramientas integradas en lugar de exponer todo el conjunto de herramientas.

Resumen de las capacidades disponibles

Puedes usar el servicio de acceso a MCP de la API de Merchant para realizar las siguientes acciones de forma autónoma:

  • Recupera el contexto detallado de estado y generación de informes para productos específicos con nombres de recursos exactos.
  • Buscar y mostrar varios productos
  • Métricas de rendimiento de la búsqueda, estados de los productos y estadísticas sobre productos populares, estadísticas de precios, visibilidad competitiva y estadísticas de afiliados de YouTube Shopping
  • Identifica los problemas a nivel de la cuenta que afectan la visibilidad de los productos o la participación en el programa.
  • Enumera, crea, recupera y verifica el estado de carga de las fuentes de datos.
  • Enumera los motivos agregados de los rechazos de productos en todo tu inventario.
  • Revisa la configuración de las mejoras automáticas para los artículos, las imágenes y el envío.
  • Verifica las regiones activas, los requisitos no cumplidos y el estado de participación de programas específicos de Merchant Center.

Cómo comenzar

Para conectar tu IDE, asistente de programación o agente al servicio de acceso al MCP de la API de Merchant, actualiza la configuración del cliente del MCP. Por ejemplo, actualiza el archivo mcp.json para Google Agent Studio, Claude Desktop, Antigravity, Visual Studio Code o tu framework de agentes personalizado.

La configuración del servicio de acceso al MCP de la API de Merchant local requiere una cuenta de servicio. El OAuth de usuario estándar no es compatible con esta ejecución local sin encabezado. Debes crear una cuenta de servicio, descargar su archivo de clave privada JSON y proporcionar la ruta de acceso a este junto con tu ID de Merchant Center específico como argumentos.

Para obtener instrucciones detalladas sobre cómo crear y descargar una cuenta de servicio, consulta la guía de cuentas de servicio.

Configuración del cliente

Configuración:

Antigravity

Sigue las instrucciones de la documentación de Antigravity.

{
    "mcpServers": {
        "merchant-data-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@google/merchant-data-mcp",
                "--credentials",
                "/path/to/your/service-account-file.json"
            ]
        }
    }
}

Claude para computadoras de escritorio

Sigue las instrucciones de la documentación de Claude Desktop.

{
    "mcpServers": {
        "merchant-data-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@google/merchant-data-mcp",
                "--credentials",
                "/path/to/your/service-account-file.json"
            ]
        }
    }
}

Ejemplos de situaciones de uso

Para ilustrar cómo puedes aprovechar el servicio de acceso a MCP de la API de Merchant para crear experiencias basadas en agentes y flujos de trabajo automatizados, considera las siguientes situaciones:

Caso 1: Diagnostica y corrige los rechazos de productos

Quieres comprender por qué un producto específico no aparece en los resultados de la Búsqueda de Google.

Instrucción del usuario:

¿Por qué se rechazó mi producto con el ID de la oferta 'offer123'?

Comportamiento del agente con MCP:

  1. El agente llama a list_products o get_product_by_name para ubicar el estado del producto.
  2. El servidor de MCP devuelve el estado del producto, incluida una lista de issues (por ejemplo, "Formato de precio incorrecto" o "Falta el valor de envío").
  3. El agente analiza los problemas y te explica la causa raíz, además de sugerirte cómo solucionarlos (por ejemplo, actualizar la información del precio).

Situación 2: Revisa la habilitación de las mejoras automáticas

Quieres verificar si tus mejoras automáticas de envío están activas.

Instrucción del usuario:

“¿Están habilitadas mis mejoras automáticas de envío?”

Comportamiento del agente con MCP:

  1. El agente llama a get_automatic_improvements para recuperar la configuración a nivel de la cuenta.
  2. El servidor de MCP devuelve la configuración que muestra el estado de las mejoras en las imágenes, los artículos y el envío.
  3. El agente confirma que las mejoras en el envío están activas o explica cómo habilitarlas si están desactivadas.

Situación 3: Genera informes y estadísticas de rendimiento

Quieres verificar rápidamente tu rendimiento reciente sin navegar por la IU de Merchant Center.

Instrucción del usuario:

"Muéstrame los 5 productos con mejor rendimiento según los clics de la semana pasada".

Comportamiento del agente con MCP:

  1. El agente crea una consulta del lenguaje de consultas de Merchant Center (MCQL) que segmenta la tabla product_performance_view, ordena por clicks DESC y limita a 5.
  2. El agente llama a report_search con la búsqueda construida.
  3. El servidor de MCP ejecuta la consulta en la base de datos de informes activos y devuelve las filas.
  4. El agente formatea los resultados en una tabla de Markdown clara para ti.

Situación 4: Crea y recupera fuentes de datos

Quieres agregar una nueva fuente de datos para subir actualizaciones de productos.

Instrucción del usuario:

"Crea una fuente de datos complementaria llamada 'price-updates' para mi cuenta de comercio".

Comportamiento del agente con MCP:

  1. El agente llama a create_data_source con la configuración especificada para registrar el feed nuevo.
  2. El servidor de MCP crea la fuente de datos y devuelve su nombre de recurso único.
  3. El agente llama a fetch_data_source para activar la descarga y el procesamiento del archivo asociado.
  4. El agente llama a get_file_upload para supervisar el progreso de la carga y confirmar el estado de procesamiento correcto de los elementos.

Herramientas y descripciones de MCP

El servicio de acceso al MCP de la API de Merchant expone las siguientes herramientas a tu agente:

Herramienta del MCP Descripción
get_product_by_name Obtiene información del producto para un comercio determinado usando el nombre exacto del recurso del producto. Devuelve el estado detallado del producto que contiene el contexto del informe y los posibles problemas a nivel del producto.
list_products Enumera o busca varios productos para un comercio determinado. Devuelve el estado detallado del producto que contiene el contexto de informes y los posibles problemas a nivel del producto para varios productos.
report_search Consultar las tablas de informes para recuperar las métricas de rendimiento de los productos, los estados de los productos, la información sobre precios y la visibilidad competitiva Consulta la guía de informes para obtener más detalles.
list_data_sources Enumera las fuentes de datos disponibles para un comercio determinado.
get_data_source Obtén detalles de una fuente de datos específica.
create_data_source Crea una fuente de datos nueva para un comercio determinado.
fetch_data_source Recupera y procesa el archivo asociado a una fuente de datos para un comercio determinado.
get_file_upload Obtén el estado de la carga de archivos más reciente para una fuente de datos determinada.
list_accounts Enumera las cuentas de un usuario determinado.
list_account_issues Enumera los problemas a nivel de la cuenta de un comercio determinado para identificar problemas en toda la cuenta.
list_programs Enumera los programas de un comercio determinado, incluido el estado de participación, las regiones activas y los requisitos no cumplidos.
list_aggregate_product_statuses Enumera los problemas agregados a nivel del producto para supervisar el estado general de tus datos de productos.
get_automatic_improvements Obtén la configuración de las mejoras automáticas, incluidas las actualizaciones de artículos, las mejoras de imágenes y las mejoras de envío.