|
Esta guía explica cómo conectar un agente de IA (Roo, Cline, Claude Desktop, Cursor, etc.) al servidor MCP de YaLIM Cloud.
Descripción General
El servidor MCP de YaLIM Cloud ya está desplegado y disponible en https://mcp.yalim.cloud. Le permite interactuar con sus instancias DHIS2 y su cuenta de YaLIM Cloud utilizando un agente de IA.
Dos modos de interacción
Modo 1 — Interacción con su instancia DHIS2: El agente de IA puede conectarse a su instancia DHIS2 y realizar operaciones (listar datos, crear unidades organizativas, importar datos, etc.). Debe proporcionar su clave API del portal YaLIM Cloud y las credenciales de su instancia DHIS2.
Modo 2 — Interacción con su cuenta YaLIM Cloud: El agente de IA puede gestionar sus instancias DHIS2 y otras aplicaciones desplegadas (verificar estado, consultar registros, reiniciar). Con su clave API, el acceso está limitado a su propio espacio (namespace) en el portal YaLIM Cloud.
| Modo |
Lo que necesita |
Ejemplos de acciones |
| Instancia DHIS2 |
Clave API + Credenciales DHIS2 |
Listar datos, crear formularios, importar/exportar |
| Cuenta YaLIM Cloud |
Solo clave API |
Verificar estado, consultar registros, reiniciar |
¿Cómo funciona? Los agentes de IA se comunican con el servidor MCP utilizando un protocolo estándar. Proporcionamos un pequeño script (conector) que permite a su agente de IA comunicarse con el servidor MCP de YaLIM Cloud alojado en nuestra infraestructura.
|
En resumen: Su agente de IA habla con el conector → El conector habla con el servidor MCP → El servidor MCP habla con su instancia DHIS2 o su cuenta YaLIM Cloud.
|
Requisitos Previos
- Python 3.8+ (no se requieren paquetes adicionales — solo usa la biblioteca estándar)
- Una clave API del Portal YaLIM Cloud (formato:
ymcp_...)
Obtener una Clave API
Las claves API se gestionan en el Portal YaLIM Cloud. Cada clave está vinculada a un usuario y proporciona acceso a las instancias DHIS2 dentro del espacio de nombres (namespace) de ese usuario.
|
Inicio Rápido
1. Configurar su clave API
|
export DHIS2_MCP_KEY="ymcp_su_clave_api_aqui"
|
2. Probar el conector
cd <carpeta-extraída>
bash scripts/test-connector.sh
|
Debería ver que el servidor responde con su lista de herramientas (36 herramientas disponibles).
3. Configurar su herramienta de IA
Consulte las secciones específicas para cada herramienta a continuación.
|
Configuración por Herramienta de IA
cursor / Roo / Cline
Estas herramientas leen el archivo .roo/mcp.json en la raíz del proyecto:
{
"mcpServers": {
"dhis2": {
"command": "python3",
"args": ["scripts/mcp-connector.py"],
"env": {
"DHIS2_MCP_URL": "https://mcp.yalim.cloud",
"DHIS2_MCP_KEY": "ymcp_su_clave_api_aqui"
}
}
}
}
|
Nota: Coloque la carpeta scripts/ del paquete del conector descargado en su directorio de proyecto, luego cree o actualice el archivo .roo/mcp.json como se muestra arriba.
|
Claude Desktop
Edite ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"dhis2": {
"command": "python3",
"args": ["/ruta/completa/hacia/scripts/mcp-connector.py"],
"env": {
"DHIS2_MCP_URL": "https://mcp.yalim.cloud",
"DHIS2_MCP_KEY": "ymcp_su_clave_api_aqui"
}
}
}
}
|
Cursor
Edite .cursor/mcp.json en la raíz del proyecto (mismo formato que Claude Desktop):
{
"mcpServers": {
"dhis2": {
"command": "python3",
"args": ["scripts/mcp-connector.py"],
"env": {
"DHIS2_MCP_URL": "https://mcp.yalim.cloud",
"DHIS2_MCP_KEY": "ymcp_su_clave_api_aqui"
}
}
}
}
|
Cualquier herramienta compatible con MCP (genérica)
El conector es un servidor MCP stdio estándar. Ejecútelo como un subproceso con estas variables de entorno:
| Variable |
Requerido |
Por defecto |
Descripción |
| DHIS2_MCP_KEY |
Sí |
— |
Su clave API ymcp_... |
| DHIS2_MCP_URL |
No |
https://mcp.yalim.cloud |
URL del servidor MCP |
|
Herramientas Disponibles
Una vez conectado, el agente de IA puede descubrir y llamar a estas categorías de herramientas:
Herramientas DHIS2 (36 herramientas)
| Herramienta |
Descripción |
| dhis2_connect | Conectar a una instancia DHIS2 (URL + credenciales) |
| dhis2_system_info | Obtener información de versión y compilación del sistema |
| dhis2_list_org_units | Listar unidades organizativas con filtros |
| dhis2_create_org_unit | Crear una nueva unidad organizativa |
| dhis2_list_data_elements | Listar/buscar elementos de datos |
| dhis2_create_data_element | Crear un nuevo elemento de datos |
| dhis2_list_datasets | Listar conjuntos de datos |
| dhis2_list_categories | Listar categorías |
| dhis2_list_indicators | Listar indicadores |
| dhis2_search_metadata | Buscar cualquier tipo de metadatos |
| dhis2_get_metadata_schema | Obtener definición de esquema de metadatos |
| dhis2_export_metadata | Exportar un paquete de metadatos |
| dhis2_get_data_values | Recuperar valores de datos |
| dhis2_import_data_values | Importar valores de datos (soporta simulación/dry-run) |
| dhis2_complete_dataset | Marcar registro del conjunto de datos como completo |
| dhis2_get_data_approval | Obtener estado de aprobación de datos |
| dhis2_validate_data | Ejecutar reglas de validación |
| dhis2_run_analytics | Ejecutar consulta de análisis agregado |
| dhis2_get_event_analytics | Consulta de análisis de eventos |
| dhis2_get_enrollment_analytics | Consulta de análisis de inscripciones |
| dhis2_list_dashboards | Listar paneles |
| dhis2_get_visualization | Obtener detalles de visualización |
| dhis2_list_programs | Listar programas de seguimiento (tracker)/eventos |
| dhis2_list_tracked_entities | Buscar instancias de entidades seguidas |
| dhis2_create_tracked_entity | Crear una entidad seguida |
| dhis2_enroll_tracked_entity | Inscribir en un programa |
| dhis2_list_events | Listar eventos |
| dhis2_create_event | Crear un evento |
| dhis2_update_event | Actualizar un evento |
| dhis2_import_tracker_data | Importación masiva de datos tracker |
| dhis2_get_system_settings | Obtener configuración del sistema |
| dhis2_run_maintenance | Ejecutar tareas de mantenimiento |
| dhis2_get_audit_log | Obtener entradas del registro de auditoría |
| dhis2_list_users | Listar usuarios DHIS2 |
| dhis2_get_sql_view | Ejecutar una vista SQL |
| dhis2_get_data_element | Obtener detalles de elemento de datos |
Herramientas de Gestión del Portal YaLIM Cloud (solo su espacio)
Estas herramientas le permiten gestionar sus instancias DHIS2 a través del portal YaLIM Cloud. El acceso está estrictamente limitado a su propio espacio de nombres:
| Herramienta |
Descripción |
| portal_list_instances | Listar todas sus instancias DHIS2 en su espacio |
| portal_get_instance | Obtener detalles y estado de una de sus instancias |
| portal_get_instance_health | Verificar si su instancia funciona correctamente |
| portal_get_instance_logs | Consultar los registros (logs) de su instancia |
| portal_restart_instance | Reiniciar su instancia DHIS2 |
| portal_stop_instance | Detener su instancia (para ahorrar recursos) |
| portal_start_instance | Iniciar una instancia detenida |
| portal_get_instance_info | Obtener información de configuración de su instancia |
|
🔒 Seguridad: Estas herramientas están limitadas a su propio espacio. No puede ver, modificar ni eliminar instancias de otros usuarios del portal YaLIM Cloud.
|
|
Ejemplo: Uso desde un Agente de IA
Una vez configurado, puede pedir al agente de IA cosas como:
Ejemplos con su instancia DHIS2
"Conéctate a romyt.dhis2.cloud y lista todas las unidades organizativas de nivel 2"
"Crea una nueva unidad organizativa llamada 'Distrito de Prueba' bajo Guinea Ecuatorial"
"Lista todos los elementos de datos que contienen 'vacuna'"
"Exporta el paquete de metadatos para el programa de malaria"
|
Ejemplos con su cuenta YaLIM Cloud
"Muéstrame el estado de mi instancia romyt"
"Verifica si mi instancia DHIS2 está funcionando correctamente"
"Muestra los registros de mi instancia para las últimas 24 horas"
"Reinicia mi instancia DHIS2"
|
El agente de IA descubrirá automáticamente las herramientas disponibles y las llamará a través del protocolo MCP.
|
Flujo de Trabajo: Cómo Usar MCP
Modo 1 — Interacción con su instancia DHIS2
Cada sesión requiere conectarse primero a una instancia DHIS2 específica:
- Dígale a la IA que se conecte usando
dhis2_connect proporcionando la URL de su instancia, su nombre de usuario y contraseña DHIS2
- El servidor MCP almacena la sesión (vinculada a su clave API)
- Todas las llamadas siguientes usan esta sesión para interactuar con su instancia
|
💡 Consejo: Puede proporcionar sus credenciales DHIS2 directamente en su mensaje a la IA. Por ejemplo: "Conéctate a miinstancia.dhis2.cloud con usuario=admin y contraseña=micontraseña"
|
Modo 2 — Interacción con su cuenta YaLIM Cloud
Para gestionar sus instancias a través del portal YaLIM Cloud, no se necesita conexión DHIS2. Su clave API es suficiente:
- El agente de IA usa su clave API para acceder solo a su espacio de nombres
- Puede listar sus despliegues, verificar su estado, consultar registros
- El acceso está estrictamente limitado a sus propias instancias — no puede ver ni modificar instancias de otros usuarios
|
Solución de Problemas
"ERROR: DHIS2_MCP_KEY environment variable is required"
Configure su clave API: export DHIS2_MCP_KEY="ymcp_..."
"Timed out waiting for SSE session"
El servidor remoto puede ser inalcanzable. Verifique:
curl -s https://mcp.yalim.cloud/healthz
# Debería devolver: ok
|
La llamada a la herramienta devuelve "authentication failed"
Su clave API puede ser inválida o estar expirada. Solicite una nueva desde el portal YaLIM Cloud.
Registros del Conector (Logs)
Todos los registros del conector se envían a stderr (stdout está reservado para el protocolo MCP). Para ver los registros:
|
DHIS2_MCP_KEY="ymcp_..." python3 scripts/mcp-connector.py 2>connector.log
|
|
Arquitectura
Así es como funciona la interacción entre su agente de IA y el servidor MCP:
Su Agente de IA (Claude, Cursor)
↓ habla en lenguaje natural
Conector MCP (script Python en su computadora)
↓ traduce a solicitudes MCP
Servidor MCP (mcp.yalim.cloud)
↓ según su solicitud:
• Modo Instancia DHIS2 → Su instancia DHIS2 (miinstancia.dhis2.cloud)
• Modo Portal YaLIM Cloud → Su espacio en el portal DHIS2 (solo sus instancias)
|
|
💡 Importante: Su clave API se inyecta automáticamente en cada solicitud por el conector. No necesita mencionarla en sus mensajes a la IA.
|
|
Guía de configuración local para el servicio MCP de YaLIM Cloud
Conectando agentes de IA a instancias DHIS2
|
|
Servidor MCP ·
Portal ·
DHIS2 Cloud
Parte del ecosistema YaLIM — Alojamiento gestionado de DHIS2.
Operado por YaLIM LLC.
|
|
