# DataFirefly MCP Commerce — Guía completa

> 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 —…

- Página: <https://www.datafirefly.com/es/documentation/serveur-mcp-commerce-agentique/>
- Idioma: es
- Actualizado el: 2026-06-17
- Otros idiomas: [fr](https://www.datafirefly.com/documentation/serveur-mcp-commerce-agentique/index.md), [en](https://www.datafirefly.com/en/documentation/serveur-mcp-commerce-agentique/index.md), [de](https://www.datafirefly.com/de/documentation/serveur-mcp-commerce-agentique/index.md), [it](https://www.datafirefly.com/it/documentation/serveur-mcp-commerce-agentique/index.md), [pl](https://www.datafirefly.com/pl/documentation/serveur-mcp-commerce-agentique/index.md), [nl](https://www.datafirefly.com/nl/documentation/serveur-mcp-commerce-agentique/index.md), [pt](https://www.datafirefly.com/pt/documentation/serveur-mcp-commerce-agentique/index.md)
- Índice: <https://www.datafirefly.com/es/documentation/llms.txt>

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.