Saltar a contenido

Bots e IA

Agapanto expone tu empresa como un conjunto de herramientas MCP (Model Context Protocol) para que un bot de Telegram, un agente de IA o Claude Code puedan consultar productos, tomar pedidos, crear facturas o leer reportes. El servidor está en /mcp-tools/mcp y se configura por empresa desde el panel de administración de Agapanto.

Permiso

La configuración MCP la activa el equipo de Agapanto por empresa. Pídela a soporte indicando qué rol debe tener el bot.

Un vistazo

Configuración MCP de Panadería Los Manjares (la gestiona el equipo de Agapanto)
Agapanto MCP Server
Activa
EmpresaPanadería Los Manjares
Telegram bot token7213…:AAH… 1
bot_secreta91f…c04e (64 caracteres) 2
Rolevendedor 3
Sesiones: telegram_id 5512… · vence en 23 h telegram_id 9930… · vence en 6 h 4
Una configuración por empresa. El rol de la configuración es el que heredan todas las sesiones creadas con ese secreto.
  1. 1 Token del bot de Telegram (opcional): solo si el bot corre sobre Telegram.
  2. 2 bot_secret: secreto de 64 caracteres generado al crear la configuración. Es la credencial del bot; trátalo como una contraseña.
  3. 3 Rol concedido: cliente, vendedor, contador o admin. Decide qué herramientas puede usar el bot.
  4. 4 Sesiones por usuario final: cada telegram_id obtiene un session_token que vence a las 24 horas y se renueva al volver a autenticar.

Cómo se autentica

Las credenciales viajan en la cabecera Authorization: Bearer …. Se aceptan dos tipos:

Credencial Quién la usa Cómo se obtiene
bot_secret Clientes fijos: Claude Code, un agente, el backend de tu bot. Lo entrega soporte al crear la configuración (o al rotarlo).
session_token Cada usuario final de un bot que atiende a muchas personas. El backend llama a la herramienta autenticar(user_id, nombre) con el bot_secret y recibe el token de ese usuario.

Con session_token las acciones quedan atribuidas al usuario (se le crea una cuenta sombra en la empresa la primera vez). La sesión hereda el rol de la configuración.

sequenceDiagram
    participant B as Backend del bot
    participant M as /mcp-tools/mcp
    B->>M: autenticar(user_id="5512…", nombre="Ana") [Bearer bot_secret]
    M-->>B: {session_token, empresa: "Panadería Los Manjares"}
    B->>M: agregar_al_carrito(producto_id=12, cantidad=2) [Bearer session_token]
    M-->>B: carrito actualizado

Ejemplo de configuración (Claude Code)

Archivo .mcp.json en el proyecto:

{
  "mcpServers": {
    "agapanto": {
      "type": "http",
      "url": "https://agapanto.com.co/mcp-tools/mcp",
      "headers": {
        "Authorization": "Bearer <bot_secret o session_token>"
      }
    }
  }
}

El transporte es Streamable HTTP. Las empresas con el flag PRODUCTS_ARE_PERSONS (facturación de servicios por concepto) usan el endpoint alterno /mcp-tools-pap/mcp, que no expone carrito ni inventario.

Herramientas disponibles

Entre paréntesis, los roles que pueden llamarlas (admin siempre puede).

  • info_empresa — contacto, horarios, costo de domicilio, pedido mínimo, si está abierta (cliente).
  • estadisticas_empresa — panel gerencial con 5 métricas de los últimos N días (admin).
  • buscar_productos, ver_producto — buscar y ver productos (cliente).
  • listar_categorias, crear_categoria, listar_productos_por_categoria, mover_productos_de_categoria (vendedor).
  • crear_producto, actualizar_producto, ajustar_inventario (vendedor).
  • ver_carrito, agregar_al_carrito, confirmar_pedido (cliente).
  • registrar_pago — referencia de transferencia, Nequi, Daviplata… para el pedido pendiente (cliente).
  • actualizar_perfil, ver_direcciones, guardar_direccion (cliente).
  • buscar_entidades, ver_entidad (vendedor, contador); crear_entidad, actualizar_entidad (vendedor).
  • crear_documento — crea una factura u otro documento con líneas (vendedor).
  • aplicar_pago_factura (vendedor); buscar_documentos, ver_documento (vendedor, contador).
  • ver_caja_diaria (vendedor, contador); cerrar_caja_diaria (vendedor).
  • ver_dashboard_ventas, historial_transacciones (vendedor, contador).
  • ver_estado_resultados, ver_aging_cartera, ver_libro_mayor, ver_balance_general (contador; requieren el flag ACCOUNTING).

Solo con PRODUCTS_ARE_PERSONS: buscar_personas (cliente), crear_persona, listar_conceptos, listar_conceptos_persona, crear_concepto, asociar_concepto_persona (vendedor) y crear_factura_concepto (admin).

También existe una API REST equivalente para bots que no hablan MCP, en /mcp/api/ (documentación en /mcp/api/docs): POST /mcp/api/auth/telegram/ con el bot_secret devuelve el session_token, y el resto de rutas (/products/, /cart/, /documents/, /caja/, /reports/…) lo usan como bearer.

Seguridad del secreto

El bot_secret da acceso a tu empresa con el rol configurado; en el panel aparece como Shared secret the bot server must send in X-Bot-Secret header, pero hoy se envía en Authorization: Bearer. Nunca lo pongas en un repositorio ni en un chat. Si se filtra, pide a soporte rotarlo; las sesiones existentes siguen vivas hasta 24 horas. Un bot para clientes debe tener rol cliente, no admin.

Todo queda dentro de tu empresa

Cada sesión está atada a una sola empresa: el bot no puede ver productos, clientes ni facturas de otra, aunque el mismo usuario de Telegram hable con dos bots distintos.

¿Problemas?
  • "Missing credentials: send an 'Authorization: Bearer ' header". La llamada llegó sin cabecera. Revisa headers en tu .mcp.json o en el cliente.
  • "Invalid bot_secret or inactive configuration". El secreto es incorrecto, fue rotado, o la configuración está desactivada.
  • La herramienta responde que el rol no tiene acceso. La configuración tiene un rol menor al necesario (por ejemplo cliente intentando crear_documento). Pide cambiar el rol o crea otra configuración para el backend.
  • Las llamadas tardan 30 s y fallan. Cada herramienta tiene un límite de 30 segundos. Si ocurre en todas, hay un problema en el servidor; avisa a soporte.
  • ver_carrito dice que la función no está disponible. Tu empresa tiene PRODUCTS_ARE_PERSONS; usa el endpoint /mcp-tools-pap/mcp y las herramientas de servicios.

Siguiente: Cliente de impresión.