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 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 estandarizado y seguro 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 fundamentados en los datos de Merchant Center.

Específicamente, permite el acceso autorizado a tus datos de Merchant Center y a los informes y 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 basado en 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 herramientas de escritura de bajo riesgo (por ejemplo, la creación de fuentes de datos) como medida de protección.

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 esté activa antes de usar estas herramientas en un entorno de producción activo.

Cuota compartida

El servicio de acceso a 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, especialmente 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 y seguridad de herramientas

En el futuro, se agregarán nuevas capacidades, en especial acciones de escritura. Te recomendamos que configures explícitamente tu cliente 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 al MCP de la API de Merchant para realizar las siguientes acciones de forma autónoma:

  • Recupera el contexto de informes y estado detallados para productos específicos con nombres de recursos exactos.
  • Publica y busca 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.
  • Enumerar, crear, recuperar y verificar 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 de tu cliente de MCP (por ejemplo, mcp.json o settings.json).

Configuración del cliente

Configuración:

Antigravity

Conéctate directamente al extremo MCP remoto alojado con un token de acceso de OAuth 2.0 (con el alcance https://www.googleapis.com/auth/content). Sigue las instrucciones de la documentación de Antigravity.

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

CLI de Claude

Agrega el extremo de MCP remoto alojado directamente en la CLI de Claude con el comando 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}"

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

cURL

Envía solicitudes estándar de JSON-RPC 2.0 directamente al extremo alojado de MCP de la API de Merchant.

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

Ejecuta una llamada a la herramienta (por ejemplo, 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}"
      }
    }
  }'

Reemplaza lo siguiente:

  • ACCOUNT_ID: Tu ID de Merchant Center
  • ACCESS_TOKEN: Es el token de autorización para realizar la llamada a la API.
  • GOOGLE_CLOUD_PROJECT_ID: Es el ID del proyecto de Google Cloud asociado a tu cuenta de Merchant Center.

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:

Situación 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 mis 5 productos con mejor rendimiento por 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 en vivo y devuelve las filas.
  4. El agente formatea los resultados en una tabla 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 de 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 de los informes y los posibles problemas a nivel del producto.
list_products Publicar o buscar 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 Obtiene 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, incluidos 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.