Integraciones: MCP, API y webhooks

Atenta es abierta: con un token el negocio conecta su Atenta a Claude, ChatGPT, Zapier, Make, n8n o a su propio código. Todo lo que se hace desde ahí es lo mismo que se haría en la app: mismos datos, mismas reglas, mismos límites.

• Servidor MCP: https://mcp.atenta.mx (Claude Code, Claude Desktop, Cursor, n8n y cualquier cliente MCP que mande una cabecera Authorization).
• API REST: https://api.atenta.mx/v1 · OpenAPI 3.1 en https://api.atenta.mx/v1/openapi.json · documentación en https://api.atenta.mx/v1/docs.
• Webhooks salientes: Atenta avisa a tu URL cuando pasa algo (mensaje, escalación, pedido, cita, pago, llamada).

Las páginas por integración, en el lenguaje del dueño, están en /integraciones.

1. El token

Se crea en la app → Ajustes → Integraciones («Conectar» en la tarjeta que quieras, con los permisos sugeridos). Tiene la forma atk_<negocio>_<32 caracteres> y se enseña una sola vez: guárdalo en un gestor de contraseñas o en una variable de entorno, nunca en un chat ni en un repositorio. Atenta guarda solo su hash y un prefijo para reconocerlo.

Permisos (elige solo los que necesite la integración):

Reglas que aplican siempre: 120 llamadas por minuto por token; cada escritura queda en la bitácora del negocio con el nombre del token; lo que solo se hace desde la app (aprobar la base, encender, cobrar el plan, campañas, borrar) responde 403 solo_desde_la_app; los teléfonos de los clientes llegan redactados; un token solo ve su negocio. Revocar un token corta la integración en el acto; «Revocar todo» (rojo, con la confirmación REVOCAR TODO) corta todas.

2. Claude Code y Claude Desktop

Claude Code (terminal). Guarda el token en una variable de entorno; la configuración lo referencia, no lo contiene:

export ATENTA_TOKEN="atk_..."   # el token que te dio la app
claude mcp add --transport http atenta https://mcp.atenta.mx --header 'Authorization: Bearer ${ATENTA_TOKEN}'
claude mcp list                 # atenta: https://mcp.atenta.mx (HTTP) - ✓ Connected

Luego, dentro de Claude Code: «¿Qué conversaciones me necesitan hoy?», «Agenda a Laura el jueves a las 5», «Hazme el resumen del día». Las herramientas se llaman atenta_chats_listar, atenta_pedidos_crear, atenta_citas_disponibles… (solo aparecen las que tu token permite; atenta_yo dice cuáles).

Claude Desktop se conecta por archivo (claude_desktop_config.json) con el puente mcp-remote, que manda el token como cabecera. Los «conectores personalizados» de claude.ai autentican por OAuth y Atenta autentica por token, así que ese camino no aplica.

{
  "mcpServers": {
    "atenta": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.atenta.mx", "--header", "Authorization: Bearer ${ATENTA_TOKEN}"],
      "env": { "ATENTA_TOKEN": "atk_..." }
    }
  }
}

Bloque genérico mcpServers para cualquier cliente que hable Streamable HTTP (Cursor, Windsurf, VS Code…):

{
  "mcpServers": {
    "atenta": {
      "type": "http",
      "url": "https://mcp.atenta.mx",
      "headers": { "Authorization": "Bearer atk_..." }
    }
  }
}

Lo que expone el servidor MCP

Solo aparecen las herramientas que el token permite (más atenta_yo, siempre).

Recursos (con base): atenta://base, atenta://menu-dia, atenta://catalogo, atenta://menu, atenta://horario, atenta://plan. Prompts: resumen_del_dia, que_contesto_a_los_escalados (propone, no manda), cobranza_de_hoy.

3. ChatGPT

El camino que funciona con un token es un GPT personalizado con Actions: en «Acciones» importa el esquema desde https://api.atenta.mx/v1/openapi.json, autenticación API Key, tipo Bearer, valor atk_.... El esquema ya trae servers, securitySchemes y una operación por acción (chats_listar, pedidos_crear, citas_disponibles…). Instrucción sugerida para el GPT: «Usa las acciones de Atenta para contestar con datos reales del negocio; nunca inventes precios ni horarios; si una acción falla, di el motivo que devuelve».

Los conectores MCP personalizados de ChatGPT autentican por OAuth o sin autenticación; Atenta autentica por token, así que para ChatGPT se usa la vía de Actions.

4. Zapier, Make y n8n

Dos direcciones.

a) Atenta → tu flujo (webhooks). Se crean en Ajustes → Integraciones → Webhooks (URL https pública + eventos) o por la API con el permiso integraciones:

curl -X POST https://api.atenta.mx/v1/webhooks \
  -H "Authorization: Bearer $ATENTA_TOKEN" -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.zapier.com/hooks/catch/123/abc","eventos":["pedido","cita","escalacion"]}'

La respuesta trae secreto (whsec_…, una sola vez). Cada evento llega como POST JSON:

{ "evento": "pedido", "tenant": "mi-negocio", "ts": "2026-09-21T18:03:11.000Z",
  "datos": { "id": 812, "cliente_id": 41, "estado": "nuevo", "total": 250, "moneda": "MXN", "canal": "whatsapp", "nuevo": true } }

con las cabeceras X-Atenta-Evento, X-Atenta-Entrega (id único: sirve para no procesar dos veces) y X-Atenta-Firma: t=<unix>,v1=<hmac>. Para verificar: v1 == HMAC_SHA256(secreto, t + "." + cuerpo_crudo) y |ahora − t| ≤ 300 s. En Node:

import { createHmac, timingSafeEqual } from "node:crypto";
export function firmaValida(secreto, cuerpoCrudo, firma) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(firma ?? ""); if (!m) return false;
  if (Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
  const esperado = createHmac("sha256", secreto).update(`${m[1]}.`).update(cuerpoCrudo).digest("hex");
  return esperado.length === m[2].length && timingSafeEqual(Buffer.from(esperado), Buffer.from(m[2]));
}

Eventos: mensaje (cada mensaje que entra o sale, con el mensaje completo), escalacion (Atenta pidió a una persona), pedido (nuevo o cambio de estado), cita (nueva, movida o cancelada), pago (link pagado o abono registrado), llamada (llamada con IA terminada). Reintentos: si tu URL no contesta 2xx, Atenta reintenta 3 veces (1 s, 5 s, 25 s); tras 20 fallos seguidos el webhook se apaga solo y lo ves en la app (con sus últimas entregas). Botón «Probar» = evento ping. Máximo 5 webhooks por negocio; solo URLs https.

En Zapier: Webhooks by Zapier → Catch Hook te da la URL; en Make: Webhooks → Custom webhook; en n8n: nodo Webhook (POST) y un nodo Crypto o Code para validar X-Atenta-Firma.

b) Tu flujo → Atenta (API REST). Cualquier ruta del negocio funciona en https://api.atenta.mx/v1/… con Authorization: Bearer atk_... (módulos HTTP Request / Webhooks by Zapier → Custom Request). Ejemplos:

# quién soy y qué puedo hacer
curl https://api.atenta.mx/v1/yo -H "Authorization: Bearer $ATENTA_TOKEN"
# pedidos nuevos
curl "https://api.atenta.mx/v1/crm/pedidos?estado=nuevo&limite=20" -H "Authorization: Bearer $ATENTA_TOKEN"
# huecos libres para agendar
curl "https://api.atenta.mx/v1/citas/disponibles?n=5" -H "Authorization: Bearer $ATENTA_TOKEN"
# agendar
curl -X POST https://api.atenta.mx/v1/citas -H "Authorization: Bearer $ATENTA_TOKEN" -H "Content-Type: application/json" \
  -d '{"inicio":"2026-09-25T17:00:00-06:00","nombre":"Laura","motivo":"corte","estado":"confirmada"}'
# contestar en un chat como persona del negocio
curl -X POST https://api.atenta.mx/v1/conversaciones/5214421234567/mensajes -H "Authorization: Bearer $ATENTA_TOKEN" -H "Content-Type: application/json" \
  -d '{"texto":"Ya salió tu pedido, llega en 20 minutos."}'
# reporte del mes
curl "https://api.atenta.mx/v1/reporte?mes=2026-09" -H "Authorization: Bearer $ATENTA_TOKEN"

Errores, siempre con error corto y motivo en humano: 401 token inválido o revocado · 403 sin_permiso (dice qué permiso falta) · 403 solo_desde_la_app · 404 no existe en este negocio · 409 estado que no lo permite (fuera_de_ventana, saldo_insuficiente…) · 422 datos incompletos (campos) · 429 más de 120 llamadas en un minuto (Retry-After). Cabeceras X-RateLimit-Limit y X-RateLimit-Remaining en cada respuesta.

5. Integradores (agencias)

Un token de integrador (atp_…, lo emite Kalia Code) da de alta negocios como lo hace el formulario de atenta.mx y lee su estado; nunca entra a los datos de un negocio (para eso está el token del dueño).

curl -X POST https://api.atenta.mx/v1/alta -H "Authorization: Bearer $ATENTA_INTEGRADOR" -H "Content-Type: application/json" \
  -d '{"negocio":"Taquería El Güero","giro":"fonda","whatsapp":"5214421234567","pais":"MX"}'
curl https://api.atenta.mx/v1/tenants -H "Authorization: Bearer $ATENTA_INTEGRADOR"
curl https://api.atenta.mx/v1/tenants/taqueria-el-guero/base -H "Authorization: Bearer $ATENTA_INTEGRADOR"

6. Seguridad, en corto

• El token solo existe en tu lado: Atenta guarda un hash. Si se filtra, revócalo en la app y crea otro.
• Todo viaja por HTTPS; las respuestas nunca traen secretos ni números completos de clientes.
• Cada escritura hecha con un token queda en la bitácora del negocio con el nombre del token.
• Las IA externas leen datos del negocio solo con un token que el dueño creó a propósito, con los permisos que eligió y mientras no lo revoque. El proveedor de esa IA es un subprocesador elegido por el propio negocio, como dice el aviso de privacidad.