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

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

Descripción general

El servicio de acceso de 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 organicen nuevas experiencias de 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 estadísticas generados por Google para realizar operaciones de solo lectura y de escritura limitada para abordar casos de uso como los siguientes:

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

Controles de seguridad y acceso

El servicio de acceso de MCP de la API de Merchant se diseñó con un enfoque prioritario en la seguridad:

• 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 la ejecución: Si bien la visibilidad de las herramientas no está restringida para el descubrimiento de agentes, la ejecución de las herramientas 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, creación de fuentes de datos) como una protección de seguridad.

Consideraciones importantes

El servicio de acceso de MCP de la API de Merchant es una versión alfa; su alcance y sus capacidades se ampliarán y podrían cambiar.

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

Cambios y lanzamientos

Los cambios pueden ocurrir sin aviso previo 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 de MCP de la API de Merchant comparte el mismo grupo de cuotas que tus llamadas a la API de Merchant estándar. La ejecución de agentes puede 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 funciones, especialmente acciones de escritura. Te recomendamos que configures de forma explícita tu cliente para que use el filtrado de herramientas integrado en lugar de exponer todo el conjunto de herramientas.

Resumen de las funciones disponibles

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

• Recupera el estado detallado y el contexto de los informes de productos específicos con nombres de recursos exactos.
• Enumera y busca varios productos.
• Consulta las métricas de rendimiento, los estados de los productos y las estadísticas sobre los productos populares, la información sobre precios, la visibilidad competitiva y las 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 los envíos.
• Verifica las regiones activas, los requisitos que no se cumplen 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 a la API de Merchant de MCP, actualiza la configuración de tu cliente de MCP (por ejemplo, mcp.json o settings.json).

Configuración del cliente

Configuraciones:

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

Situaciones de uso de ejemplo

Para ilustrar cómo puedes aprovechar el servicio de acceso de MCP de la API de Merchant para crear experiencias de 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, y te sugiere cómo solucionarlo (por ejemplo, actualizando la información de precios).

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

Quieres verificar si las 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 de imágenes, artículos y envíos.
3. El agente confirma que las mejoras de 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 consultar 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 construye una consulta en el lenguaje de consulta de Merchant Center (MCQL) orientada a la tabla product_performance_view, ordenada por clicks DESC y limitada a 5.
2. El agente llama a report_search con la consulta 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 les da formato a 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 comerciante".

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 de MCP y descripciones

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