PS PrestaShop PrestaShop Intermedio

DataFirefly MCP Commerce — Guía completa

Instalar, configurar y conectar el servidor MCP: endpoint, OAuth 2.1, tokens Bearer, herramientas, scopes y modos de pedido para PrestaShop 8 y 9.

Actualizado Versión del módulo 1.0.0

El módulo DataFirefly MCP Commerce convierte tu tienda PrestaShop en un servidor MCP (Model Context Protocol) que los agentes de IA — ChatGPT, Claude, Claude Desktop, Claude Code, n8n — pueden usar directamente para recorrer el catálogo, montar carritos y preparar pedidos. Esta guía cubre la instalación, el endpoint, la doble autenticación (OAuth 2.1 y tokens Bearer), la conexión de los principales agentes, las herramientas expuestas, los scopes, los modos de pedido y la resolución de problemas.

Requisitos

  • PrestaShop 8.0 a 9.x.
  • PHP 7.4 a 8.3 con la extensión cURL activa.
  • Una tienda servida por HTTPS (obligatorio para los conectores de IA).
  • Recomendado: las URL amigables activadas (Parámetros avanzados > SEO & URL) para endpoints limpios.

El módulo también funciona sin URL amigables: expone entonces enlaces de reserva basados en index.php, mostrados en la pestaña Conectar un agente de la configuración.

Instalación

  1. En el back office, abre Módulos > Gestor de módulos, luego Subir un módulo y suelta el archivo dfmcpcommerce.zip.
  2. Una vez instalado, abre la configuración con el botón Configurar.
  3. La instalación crea las tablas técnicas (tokens, clientes OAuth, carritos, registro, limitador de tasa) y activa el servidor por defecto.

Tu endpoint MCP

La URL del servidor MCP se muestra en la pestaña Conectar un agente. Con las URL amigables, se parece a:

https://tu-tienda.com/mcp

Esta es la URL que pegas en el conector del agente. El transporte es Streamable HTTP (JSON-RPC 2.0): un único endpoint, por POST.

Autenticación: dos mecanismos

El módulo gestiona dos modos de autenticación en paralelo, según el cliente utilizado.

OAuth 2.1 — conectores web (Claude.ai, ChatGPT)

Los conectores web de Claude.ai y ChatGPT solo aceptan OAuth: sin token pegado, sin token en la URL. El módulo incluye un servidor de autorización OAuth 2.1 completo (authorization code + PKCE S256, metadatos de recurso protegido y registro dinámico de cliente). El agente se registra solo y abre una pantalla de consentimiento donde el cliente inicia sesión y aprueba el acceso.

Tokens Bearer — API, Desktop, CLI, n8n

Para la API de Anthropic (conector MCP), Claude Desktop, Claude Code o n8n, creas un token Bearer estático en la pestaña Tokens de acceso y lo pasas en la cabecera Authorization: Bearer.

Los tokens se muestran una sola vez al crearlos y se almacenan con hash (SHA-256). Cópialo de inmediato; no se volverá a mostrar en texto plano.

Conectar Claude.ai o ChatGPT (web)

  1. Mantén OAuth 2.1 activado en la pestaña Ajustes.
  2. En el agente, añade un conector personalizado y pega la URL del servidor MCP.
  3. El agente descubre automáticamente la autenticación, se registra y abre la pantalla de consentimiento.
  4. El cliente inicia sesión en su cuenta de la tienda y aprueba los scopes solicitados. Sin token que introducir.

Conectar la API de Anthropic, Claude Desktop, Claude Code o n8n

  1. Abre la pestaña Tokens de acceso, elige los scopes y haz clic en Crear token.
  2. Copia el token mostrado.
  3. Configura el conector con la URL del servidor MCP y la cabecera Authorization: Bearer TU_TOKEN.

Scopes

Cada acceso está limitado por scopes, solicitados por el agente y concedidos en el consentimiento (OAuth) o portados por el token (Bearer):

  • catalog:read — búsqueda y fichas de productos, categorías, info de la tienda, transportistas.
  • cart:write — creación y gestión de carritos.
  • order:write — preparación de pedidos.

Herramientas expuestas

Hay nueve herramientas disponibles. Cada una se activa o desactiva individualmente en la pestaña Ajustes, y está sujeta al scope correspondiente.

  • search_products — búsqueda por palabra clave, referencia o EAN, con filtros de categoría y precio.
  • get_product — ficha detallada de un producto (precio, stock, variantes, imágenes).
  • list_categories — árbol de categorías.
  • get_shop_info — nombre, idiomas, monedas y países de envío.
  • get_carriers — transportistas disponibles.
  • create_cart — creación de un carrito.
  • add_to_cart — añadir un producto al carrito.
  • view_cart — contenido y totales del carrito.
  • create_order — finalización, según el modo de pedido configurado.

Desactiva las herramientas que no quieras exponer. Por ejemplo, dejar solo catalog:read y sus herramientas convierte el módulo en un servidor de catálogo de solo lectura para los agentes.

Modos de pedido

La pestaña Ajustes ofrece dos comportamientos para create_order.

Modo traspaso (por defecto)

El agente arma el carrito y devuelve una URL de pago segura. Al seguirla, el cliente encuentra ese mismo carrito en su sesión y completa el pago en el proceso habitual de PrestaShop. Ningún dato de pago pasa por el agente: cero exposición PCI.

Modo pedido

El agente crea directamente un pedido en espera de pago, en el estado configurable (por defecto «Transferencia bancaria en espera»). Pensado para B2B, contra reembolso o presupuestos.

En modo pedido, el pedido se crea sin pago cobrado. El pago se cobra después según el método asociado al estado de pedido elegido.

Ajustes adicionales

  • Exigir autenticación: recomendado. Una solicitud no autenticada desencadena el flujo OAuth (respuesta 401 con cabecera WWW-Authenticate).
  • Lectura anónima del catálogo: permite llamadas catalog:read sin token, para exponer un catálogo público.
  • Límite de tasa: número de solicitudes por minuto y por IP (por defecto 120), en ventana deslizante.
  • Registro y retención: traza cada solicitud (método, herramienta, estado, duración) en la pestaña Registro de actividad, con un número de filas conservadas configurable.

Descubrimiento y endpoints

Los agentes descubren el servidor automáticamente. Las URL útiles se listan en la pestaña Conectar un agente:

  • Protected Resource Metadata (RFC 9728) — /.well-known/oauth-protected-resource.
  • Authorization Server Metadata (RFC 8414) — /.well-known/oauth-authorization-server.
  • Registro dinámico de cliente (RFC 7591), autorización y token: endpoints OAuth gestionados por el módulo.

Incluso sin URL amigables, la cabecera WWW-Authenticate devuelta por el endpoint siempre apunta a la URL de descubrimiento correcta basada en index.php: la conexión funciona en todos los casos.

Seguridad

  • Todos los tokens se almacenan con hash SHA-256, nunca en texto plano.
  • PKCE S256 obligatorio, redirect_uri validadas, códigos de autorización de un solo uso, rotación de refresh tokens.
  • Limitación de tasa por IP y registro de actividad consultable.
  • CORS gestionado para los conectores web. Compatibilidad multitienda, multiidioma y multidivisa nativa.

Resolución de problemas

  • El agente web no se conecta: comprueba que la tienda esté en HTTPS y que OAuth esté activado. Asegúrate de pegar la URL /mcp (no una página del back office).
  • El cliente API devuelve 401: el token Bearer falta, está revocado o caducado. Crea uno nuevo en la pestaña Tokens de acceso y comprueba la cabecera Authorization.
  • Una herramienta no aparece: probablemente está desactivada en Ajustes, o no se concedió el scope correspondiente.
  • Error 429: se ha alcanzado el límite de tasa por IP. Aumenta el umbral en Ajustes si es necesario.
  • El enlace de pago traspasado caduca: los enlaces de carrito tienen una vida útil limitada; pide al agente que regenere el carrito.

Desinstalación

La desinstalación elimina las tablas del módulo (tokens, clientes OAuth, carritos, registro, limitador) y sus variables de configuración. Tus productos, clientes y pedidos no se ven afectados. Para una simple actualización, basta con reemplazar los archivos: el esquema y los tokens existentes se conservan.

¿Te ha resultado útil esta página?

¿Sigues atascado? Contacta con soporte