---
title: 'Guper por IA (MCP)'
description: 'Conecta un asistente de IA a tu organización y opera Guper conversando, con los permisos que ya tienes.'
---

# Guper por IA (MCP)

Tu organización tiene una dirección que cualquier asistente de IA compatible con **MCP** (Model Context Protocol) entiende. Una vez conectado, conversas con el asistente y él usa Guper por ti — consulta un cliente, lee un saldo, arma una audiencia, crea una campaña.

```
https://{organization}.myguper.com/mcp
```

Funciona en Claude, en Cursor, en ChatGPT y en cualquier cliente que hable MCP.

**No hay llave que generar ni SDK que instalar.** El inicio de sesión es el mismo del panel, en el navegador — y el asistente recibe exactamente los permisos que ya tienes ahí.

## Conectando

1. En tu asistente, abre el área de conectores. En Claude: **Configuración → Conectores → Agregar conector personalizado**. En Cursor el campo se llama *MCP server URL*.
2. Pega la dirección de tu organización — `https://{organization}.myguper.com/mcp`.
3. Se abre una ventana del navegador con la pantalla de inicio de sesión de Guper. Entra con **el mismo correo y contraseña del panel**.
4. Listo.

La aplicación se registra sola en tu organización. El acceso es **tuyo, individual** — no de la empresa. Si te vas, tu acceso se va contigo, sin que nadie tenga que cambiar credenciales de nadie más.

¿Usas más de una organización? Cada una es un conector aparte, con su propia dirección. Un acceso nunca alcanza a la otra.

## Qué puedes pedir

El asistente busca en un catálogo de operaciones antes de actuar, así que conviene usar las palabras del día a día:

- *"¿cuál es el saldo de cashback del cliente 4,482,109?"*
- *"¿cuántos pedidos hizo la tienda 1838 esta semana?"*
- *"arma una audiencia de quienes compraron vino en los últimos 90 días"*
- *"crea una campaña de cumpleaños con 10% de cashback"*
- *"¿por qué este cliente no pudo canjear?"*

Si responde que no encontró nada, prueba con términos del dominio — cashback, canje, audiencia, campaña, pedido — en vez de describir el problema. La búsqueda es léxica.

## Lo que no hace por su cuenta

**Toda operación que mueve dinero exige confirmación explícita.** Son 41 operaciones: ajuste de saldo, cancelación, crédito. El asistente pregunta antes y no ejecuta sin tu "sí".

**Las operaciones no idempotentes exigen una llave de repetición.** Eso impide que una falla de red convierta una campaña en dos.

**No ves lo que no puedes ver.** Las operaciones fuera de tu permiso ni siquiera llegan al asistente — no es que lo intente y sea rechazado: desde su punto de vista no existen. Un perfil de atención típico ve cerca de una quinta parte del catálogo.

## Para quien administra

### Quién puede usarlo

Cualquier persona con inicio de sesión **de panel** (`admin` o `staff`) y un perfil de acceso asignado. El inicio de sesión de cliente final no entra.

Un usuario sin perfil de acceso recibe un aviso en pantalla y la conexión no se completa. Un acceso que no puede hacer nada haría que el asistente respondiera "no encontré nada" a todo, lo cual es indistinguible de un sistema roto.

### Cómo controlar lo que hace la IA

Con los **perfiles de acceso del panel**, los mismos de siempre. No hay pantalla nueva ni permiso paralelo: lo que el asistente puede hacer es literalmente lo que está en **Configuraciones → Equipo → Perfiles de acceso**.

Quien tiene `Clientes 360` en *ver* consulta clientes por IA pero no los modifica. Quien no tiene `Tarjetas de lealtad` no ve nada de cashback.

### Cómo cortar el acceso de alguien

Desactiva al usuario en el panel. El nuevo inicio de sesión se bloquea de inmediato, y el acceso existente cae en la siguiente renovación — como máximo una hora.

¿Cambiaste un permiso? Se aplica en la siguiente renovación, también en hasta una hora. Lo que el asistente puede hacer se vuelve a verificar en cada renovación, nunca se hereda.

### Duración

El acceso vale 1 hora y se renueva solo por hasta 30 días sin volver a iniciar sesión. Después de eso, se entra de nuevo.

### Intentos de contraseña

Ocho intentos incorrectos bloquean ese correo por 15 minutos. El bloqueo es por correo, no por red — el error de una persona no afecta a la oficina.

## Para quien integra un cliente propio

El MCP de Guper sigue **OAuth 2.1 con PKCE** y los estándares que los clientes MCP esperan. No necesitas registrar nada a mano: el registro es dinámico.

El punto de partida es el metadata del recurso protegido ([RFC 9728](https://www.rfc-editor.org/rfc/rfc9728)):

```bash
curl https://{organization}.myguper.com/.well-known/oauth-protected-resource
```

Apunta al authorization server, cuyo metadata ([RFC 8414](https://www.rfc-editor.org/rfc/rfc8414)) responde en:

```bash
curl https://{organization}.myguper.com/.well-known/oauth-authorization-server/api/connect
```

De ahí en adelante el flujo es el estándar:

| etapa | endpoint |
|---|---|
| registro dinámico ([RFC 7591](https://www.rfc-editor.org/rfc/rfc7591)) | `POST /api/connect/oauth/register` |
| autorización | `GET /api/connect/oauth/authorize` |
| canje del code y renovación | `POST /api/connect/oauth/token` |
| revocación ([RFC 7009](https://www.rfc-editor.org/rfc/rfc7009)) | `POST /api/connect/oauth/revoke` |
| llave pública | `GET /api/connect/oauth/jwks` |

Detalles que tu cliente debe respetar:

- **PKCE es obligatorio, y solo `S256`.** `plain` no se acepta.
- **La `redirect_uri` se compara por igualdad exacta.** Sin prefijos, sin comodines. Siempre `https://`; `http://` solo en loopback (`127.0.0.1`, `localhost`), como indica la [RFC 8252](https://www.rfc-editor.org/rfc/rfc8252).
- **Solo clientes públicos** (`token_endpoint_auth_method: none`).
- **El `code` vale 2 minutos y sirve una vez.** Presentarlo de nuevo termina la sesión completa, por seguridad.
- **El refresh rota.** Cada uso emite uno nuevo; presentar uno ya gastado termina la sesión completa.

El token es un JWT firmado en RS256, con `aud` igual a la URI canónica del recurso de tu organización (`https://{organization}.myguper.com/mcp`). Un token emitido para una organización **falla** la validación en otra — el aislamiento viene del protocolo.

El `scope` trae los permisos en formato `recurso.nivel`, los mismos del panel:

```
customer.360.edit customer.360.messages.view customer.addBalance.full order.edit
```

## ¿Esto cambia algo en mi integración actual?

**No.** `apiKey`/`apiSecret` → token → llamadas siguen exactamente igual, y ningún endpoint cambió. MCP es un camino nuevo, por persona, al lado de lo que ya existe.

La integración servidor a servidor continúa por el camino de siempre — ver [Autenticación](/docs/{lang}/guides/authentication).

## Problemas comunes

| síntoma | causa probable | qué hacer |
|---|---|---|
| "no pude conectar" | dirección de la organización equivocada | revisar el subdominio en la dirección |
| el inicio de sesión abre y vuelve con error | cambió la dirección de retorno del cliente | quitar y volver a agregar el conector — se registra de nuevo |
| "aplicación no reconocida" | registrada en otra organización | es lo esperado: cada organización tiene su registro. Agrega el conector aquí |
| el asistente no encuentra nada | la búsqueda es léxica | usar términos del dominio, no la descripción del problema |
| siempre pide confirmación | operación financiera | es el diseño: 41 operaciones mueven dinero |
| falta una operación esperada | fuera de tu perfil | revisar **Configuraciones → Equipo → Perfiles de acceso** |
| "demasiados intentos" | 8 contraseñas incorrectas | esperar 15 minutos |

## Ver también

- [Autenticación](/docs/{lang}/guides/authentication) — el camino `apiKey`/`apiSecret`, para integración de sistema
- [Panorama de integración](/docs/{lang}/guides/integration-landscape) — cómo encajan las piezas
