Integración agentiva por MCP: opera pedidos y clientes en lenguaje natural

Los equipos de lealtad y operaciones están automatizando cada vez más con agentes de IA: campañas que crean pedidos, scripts que ajustan las billeteras de puntos, asistentes que consultan el catálogo antes de lanzar una promoción. Hasta ahora, esto implicaba integrar manualmente la API REST, manejar la idempotencia y memorizar los puntos finales. TPP Ops cierra esa brecha con un servidor MCP (Modelo de Protocolo de Contexto) que envuelve la API pública /api/v1/* como herramientas que un agente puede invocar en lenguaje natural.

No es una segunda API ni un acceso diferente al backoffice interno. Es un adaptador de protocolo: cada llamada MCP se traduce en una solicitud HTTP a la API que los socios ya utilizan, con el mismo portador, los mismos alcances y las mismas reglas de sub-marca. Si el token no puede crear pedidos, la herramienta devuelve forbidden — el agente no puede eludir la autorización.

Lo que un agente conectado puede hacer

Las herramientas se generan automáticamente a partir del registro de operaciones de la API. Cuando agregamos un nuevo punto final, aparece como una herramienta MCP sin trabajo adicional. El catálogo cubre el ciclo operativo que importa a los integradores y equipos de producto.

• Clientes: listar, crear, actualizar, consultar monedas y ajustar saldos (bulk_adjust_customer_coins incluido).

• Pedidos: reserve_order, listar, consultar detalles, cancel_order y gestionar envíos.

• Catálogo: tiendas, catálogos y search_products con precios enmascarados.

• Sesiones: create_store_session para la entrega de SSO del jugador.

Autenticación y alcance

El servidor MCP no almacena sus propias credenciales. Toma el encabezado Autorización: Bearer de la solicitud entrante — tu clave API tpp_live_* o tpp_test_* — y la reenvía tal cual a la API. La clave está limitada a una sub-marca: el agente solo ve y toca datos de ese inquilino. El velo del proveedor, límite de tasa, auditoría e idempotencia se heredan del envoltorio withApiKey; el MCP no reimplementa la lógica de negocio.

Principio de menor privilegio: crea una clave con solo los alcances que el agente necesita. Un token de solo lectura no puede escribir incluso si el aviso lo solicita — la API responde 403 y el agente recibe un error procesable con el alcance faltante.

Idempotencia en operaciones monetarias

Los puntos finales que mueven dinero o crean clientes requieren Idempotency-Key. Un agente que reintenta por duda podría duplicar un cargo sin una clave estable. El MCP genera automáticamente un UUID por llamada y expone un argumento opcional idempotency_key para reintentos deliberados: la API devuelve la misma respuesta en caché con Idempotent-Replay: true.

Cómo conectarlo

En la oficina de operaciones de TPP, ve a Sub-marca → Claves API y crea un token con los alcances mínimos. En ChatGPT (Modo Desarrollador), agrega un conector personalizado con la URL https://<tu-dominio>/api/mcp y autenticación de clave API / Bearer. Claude, Cursor y n8n utilizan la misma URL y encabezado.

La guía humana vive en /api/v1/mcp; el manifiesto legible por máquina con JSON-Schema para cada herramienta, en /api/mcp/tools — el equivalente de MCP a OpenAPI. ChatGPT ejecuta tools/list al conectarse y ya puede operar: "crear un pedido para este cliente", "¿cuántas monedas tiene el segmento VIP?", "buscar regalos de juegos en el catálogo".

¿Por qué MCP y no solo REST?

REST sigue siendo la opción para integraciones clásicas de servidor a servidor. MCP desbloquea el mismo backend para flujos agénticos: prototipado rápido, operaciones asistidas por IA, conectores en ChatGPT sin escribir tu propio middleware. Una única fuente de verdad, dos formas de consumirlo.

El servidor es sin estado (HTTP transmitible), escala horizontalmente sin Redis, y se despliega con la misma aplicación en POST /api/mcp. Si ya estás operando lealtad con TPP y quieres que tus agentes creen pedidos, verifiquen stock o ajusten monedas sin usar curl, MCP es la capa que falta.