Conceptos Fundamentales: La Jerarquía Operativa

Para dominar el Centro de Acción y las herramientas de IA en Sfero, es crucial entender cómo interactúan los tres roles principales en el ecosistema. Cada uno tiene un propósito específico y herramientas dedicadas.

1. El Administrador (Estratega)

Es el dueño de la organización en Sfero. Su rol es Estratégico.

• Responsabilidad: Monitorear la gestión general de la organización.
• Alcance: Todos los espacios de trabajo.
• Acciones Clave: Creación de usuarios (Gestores), Creación y gestión de Workspaces, Monitoreo de resultados de Insights.

2. El Gestor (Táctico)

Es el líder operativo de un equipo o área (Workspace). Su rol es Táctico.

• Responsabilidad: Diseñar y asegurar la ejecución de la estrategia de evaluación.
• Alcance: Sus Espacios de Trabajo (Workspaces) asignados.
• Acciones Clave: Creación de Sujetos de EvaluaciónEvaluadores, Plantillas y Asignaciones. Monitoreo del equipo Evaluador.

3. El Evaluador (Ejecutor)

Es quien está en el campo o en el punto de inspección. Su rol es Ejecutivo.

• Responsabilidad: Capturar la realidad con precisión y veracidad.
• Alcance: Las asignaciones que recibe en su bandeja de entrada.
• Acciones Clave: Capturar información en las plantillas asignadas (Online/Scan to Fill). Sincronizar datos.

---

Asignación vs. Evaluación

Es fundamental distinguir entre la orden y la ejecución:

La Asignación (El Plano)

Es la orden administrativa creada por el Gestor. Contiene las instrucciones: Quién evalúa, Qué evalúa, Cuándo y con Qué plantilla. Mientras está como asignación, es un plan pendiente de ejecución.

La Evaluación (La Realidad)

Es el registro resultante creado por el Evaluador. Una vez el evaluador completa la asignación, esta se convierte en una evaluación con datos, evidencia y resultados que alimentan la inteligencia del sistema.

---

El MCP Server: Integración con Agentes Autónomos

El MCP Server de Sfero es una capa de integración basada en el Model Context Protocol que permite a agentes de IA externos y sistemas autónomos interactuar con Sfero de forma programática. Mientras que los tres roles descritos arriba operan a través de la interfaz web, el MCP Server abre una puerta para que herramientas como Claude, sistemas CMMS, plataformas de mantenimiento o cualquier agente compatible con MCP participen en el ciclo operativo.

¿Para qué sirve?

El caso de uso central es el cierre del ciclo operativo: Sfero detecta un problema (via triage de IA), y un sistema externo —por ejemplo, un sistema de gestión de órdenes de trabajo— recibe esa alerta, crea la orden de trabajo, ejecuta la corrección, y finalmente le notifica a Sfero que el problema fue resuelto. Todo esto puede suceder de forma automatizada, sin intervención humana manual.

Autenticación: API Keys

El acceso al MCP Server se controla mediante API Keys con prefijo sfero_. Solo el Administrador puede crearlas o revocarlas desde la configuración de la organización. Cada clave:

• Se muestra una sola vez al momento de creación — no es recuperable después.
• Se almacena como hash SHA-256 en Cloudflare KV (el secreto nunca persiste en base de datos).
• Queda asociada a la organización, no a un usuario individual.
• Puede ser revocada con efecto inmediato.

Herramientas Disponibles

El MCP Server expone herramientas organizadas por dominio:

Dominio	Herramientas
Workspaces	list_workspaces, get_workspace_catalogs
Sujetos de Evaluación	list_evaluation_objects, create_evaluation_object, get_evaluation_object
Plantillas	list_templates, get_template
Asignaciones	list_assignments, create_assignment y otras operaciones de ciclo de vida
Inteligencia	get_assignment_results (triage, briefing ejecutivo, análisis predictivo)
Cierre Operativo	record_operational_feedback (registra la resolución desde sistemas externos)
Webhooks	register_webhook, list_webhooks, revoke_webhook

Webhooks: Notificaciones en Tiempo Real

En lugar de hacer polling, un agente puede registrar un webhook para recibir una notificación push cuando Sfero genera nuevos insights para una evaluación. El evento insights.generated entrega un payload liviano con el evaluation_id, y el agente puede entonces llamar a get_assignment_results para obtener el análisis completo.

Cada entrega viene firmada con HMAC-SHA256 usando el secreto del webhook, lo que permite al receptor verificar que el mensaje proviene de Sfero. Una organización puede tener hasta 5 webhooks activos simultáneamente. Si un webhook falla 10 veces consecutivas, se desactiva automáticamente.

Flujo Típico de Integración

1. El Administrador crea una API Key desde la configuración y la entrega al equipo de integración.
2. El agente externo se conecta al MCP Server usando la clave y llama a list_workspaces para descubrir el entorno.
3. Registra un webhook para el evento insights.generated.
4. Cuando un Evaluador completa una evaluación, Sfero procesa la IA y dispara el webhook.
5. El agente recibe la notificación, consulta get_assignment_results, y actúa (abre una orden de trabajo, envía una alerta, etc.).
6. Una vez resuelta la situación, el agente llama a record_operational_feedback para cerrar el ciclo en Sfero.