|
Ce guide explique comment connecter un agent IA (Roo, Cline, Claude Desktop, Cursor, etc.) au serveur MCP de YaLIM Cloud.
Vue d'ensemble
Le serveur MCP de YaLIM Cloud est déjà déployé et disponible à l'adresse https://mcp.yalim.cloud . Il vous permet d'interagir avec vos instances DHIS2 et votre compte YaLIM Cloud en utilisant un agent IA.
Deux modes d'interaction
Mode 1 — Interaction avec votre instance DHIS2 : L'agent IA peut se connecter à votre instance DHIS2 et effectuer des opérations (lister les données, créer des unités d'organisation, importer des données, etc.). Vous devez fournir votre clé API du portail YaLIM Cloud et les identifiants de votre instance DHIS2.
Mode 2 — Interaction avec votre compte YaLIM Cloud : L'agent IA peut gérer vos instances DHIS2 et autres applications déployées (vérifier l'état, consulter les journaux, redémarrer). Avec votre clé API, l'accès est limité à votre propre espace (namespace) sur le portail YaLIM Cloud.
| Mode |
Ce dont vous avez besoin |
Exemples d'actions |
| Instance DHIS2 |
Clé API + Identifiants DHIS2 |
Lister les données, créer des formulaires, importer/exporter |
| Compte YaLIM Cloud |
Clé API uniquement |
Vérifier l'état, consulter les journaux, redémarrer |
Comment ça marche ? Les agents IA communiquent avec le serveur MCP en utilisant un protocole standard. Nous fournissons un petit script (connecteur) qui permet à votre agent IA de communiquer avec le serveur MCP de YaLIM Cloud hébergé sur notre infrastructure.
|
En résumé : Votre agent IA parle au connecteur → Le connecteur parle au serveur MCP → Le serveur MCP parle à votre instance DHIS2 ou votre compte YaLIM Cloud.
|
Prérequis
- Python 3.8+ (aucun paquet supplémentaire requis — utilise uniquement la bibliothèque standard)
- Une clé d'API du Portail YaLIM Cloud (format :
ymcp_...)
Obtenir une clé d'API
Les clés d'API sont gérées dans le Portail YaLIM Cloud. Chaque clé est liée à un utilisateur et donne accès aux instances DHIS2 au sein de l'espace de noms (namespace) de cet utilisateur.
|
Démarrage Rapide
1. Configurer votre clé d'API
|
export DHIS2_MCP_KEY="ymcp_votre_cle_api_ici"
|
2. Tester le connecteur
cd <dossier-extrait>
bash scripts/test-connector.sh
|
Vous devriez voir le serveur répondre avec sa liste d'outils (36 outils disponibles).
3. Configurer votre outil d'IA
Voir les sections spécifiques à chaque outil ci-dessous.
|
Configuration par Outil d'IA
cursor / Roo / Cline
Ces outils lisent le fichier .roo/mcp.json à la racine du projet :
{
"mcpServers": {
"dhis2": {
"command": "python3",
"args": ["scripts/mcp-connector.py"],
"env": {
"DHIS2_MCP_URL": "https://mcp.yalim.cloud",
"DHIS2_MCP_KEY": "ymcp_votre_cle_api_ici"
}
}
}
}
|
Note : Placez le dossier scripts/ du package du connecteur téléchargé dans votre répertoire de projet, puis créez ou mettez à jour le fichier .roo/mcp.json comme indiqué ci-dessus.
|
Claude Desktop
Modifiez ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows) :
{
"mcpServers": {
"dhis2": {
"command": "python3",
"args": ["/chemin/complet/vers/scripts/mcp-connector.py"],
"env": {
"DHIS2_MCP_URL": "https://mcp.yalim.cloud",
"DHIS2_MCP_KEY": "ymcp_votre_cle_api_ici"
}
}
}
}
|
Cursor
Modifiez .cursor/mcp.json à la racine du projet (même format que Claude Desktop) :
{
"mcpServers": {
"dhis2": {
"command": "python3",
"args": ["scripts/mcp-connector.py"],
"env": {
"DHIS2_MCP_URL": "https://mcp.yalim.cloud",
"DHIS2_MCP_KEY": "ymcp_votre_cle_api_ici"
}
}
}
}
|
Tout outil compatible MCP (générique)
Le connecteur est un serveur MCP stdio standard. Exécutez-le comme un sous-processus avec ces variables d'environnement :
| Variable |
Requis |
Par défaut |
Description |
| DHIS2_MCP_KEY |
Oui |
— |
Votre clé d'API ymcp_... |
| DHIS2_MCP_URL |
Non |
https://mcp.yalim.cloud |
URL du serveur MCP |
|
Outils Disponibles
Une fois connecté, l'agent IA peut découvrir et appeler ces catégories d'outils :
Outils DHIS2 (36 outils)
| Outil |
Description |
| dhis2_connect | Connecter à une instance DHIS2 (URL + identifiants) |
| dhis2_system_info | Obtenir la version du système et les informations de build |
| dhis2_list_org_units | Lister les unités d'organisation avec des filtres |
| dhis2_create_org_unit | Créer une nouvelle unité d'organisation |
| dhis2_list_data_elements | Lister/rechercher des éléments de données |
| dhis2_create_data_element | Créer un nouvel élément de données |
| dhis2_list_datasets | Lister les ensembles de données (datasets) |
| dhis2_list_categories | Lister les catégories |
| dhis2_list_indicators | Lister les indicateurs |
| dhis2_search_metadata | Rechercher n'importe quel type de métadonnées |
| dhis2_get_metadata_schema | Obtenir la définition du schéma des métadonnées |
| dhis2_export_metadata | Exporter un package de métadonnées |
| dhis2_get_data_values | Récupérer des valeurs de données |
| dhis2_import_data_values | Importer des valeurs de données (supporte la simulation/dry-run) |
| dhis2_complete_dataset | Marquer l'enregistrement du dataset comme complet |
| dhis2_get_data_approval | Obtenir le statut d'approbation des données |
| dhis2_validate_data | Exécuter les règles de validation |
| dhis2_run_analytics | Exécuter une requête d'analyse agrégée |
| dhis2_get_event_analytics | Requête d'analyse d'événements |
| dhis2_get_enrollment_analytics | Requête d'analyse des inscriptions |
| dhis2_list_dashboards | Lister les tableaux de bord |
| dhis2_get_visualization | Obtenir les détails d'une visualisation |
| dhis2_list_programs | Lister les programmes de suivi (tracker)/événements |
| dhis2_list_tracked_entities | Rechercher des instances d'entités suivies |
| dhis2_create_tracked_entity | Créer une entité suivie |
| dhis2_enroll_tracked_entity | Inscrire à un programme |
| dhis2_list_events | Lister les événements |
| dhis2_create_event | Créer un événement |
| dhis2_update_event | Mettre à jour un événement |
| dhis2_import_tracker_data | Importation en masse de données tracker |
| dhis2_get_system_settings | Obtenir les paramètres du système |
| dhis2_run_maintenance | Déclencher des tâches de maintenance |
| dhis2_get_audit_log | Obtenir les entrées du journal d'audit |
| dhis2_list_users | Lister les utilisateurs DHIS2 |
| dhis2_get_sql_view | Exécuter une vue SQL |
| dhis2_get_data_element | Obtenir les détails d'un élément de données |
Outils de gestion du Portail YaLIM Cloud (accès à votre espace uniquement)
Ces outils vous permettent de gérer vos instances DHIS2 via le portail YaLIM Cloud. L'accès est strictement limité à votre propre espace (namespace) :
| Outil |
Description |
| portal_list_instances | Lister toutes vos instances DHIS2 dans votre espace |
| portal_get_instance | Obtenir les détails et le statut d'une de vos instances |
| portal_get_instance_health | Vérifier si votre instance fonctionne correctement |
| portal_get_instance_logs | Consulter les journaux (logs) de votre instance |
| portal_restart_instance | Redémarrer votre instance DHIS2 |
| portal_stop_instance | Arrêter votre instance (pour économiser des ressources) |
| portal_start_instance | Démarrer une instance arrêtée |
| portal_get_instance_info | Obtenir les informations de configuration de votre instance |
|
🔒 Sécurité : Ces outils sont limités à votre propre espace. Vous ne pouvez pas voir, modifier ou supprimer les instances d'autres utilisateurs du portail YaLIM Cloud.
|
|
Exemple : Utilisation depuis un Agent IA
Une fois configuré, vous pouvez demander à l'agent IA des choses comme :
Exemples avec votre instance DHIS2
"Connecte-toi à romyt.dhis2.cloud et liste toutes les unités d'organisation de niveau 2"
"Crée une nouvelle unité d'organisation appelée 'Test District' sous Guinée Équatoriale"
"Liste tous les éléments de données contenant 'vaccin'"
"Exporte le package de métadonnées pour le programme de paludisme"
|
Exemples avec votre compte YaLIM Cloud
"Montre-moi le statut de mon instance romyt"
"Vérifie si mon instance DHIS2 fonctionne correctement"
"Montre les journaux de mon instance pour les dernières 24 heures"
"Redémarre mon instance DHIS2"
|
L'agent IA découvrira automatiquement les outils disponibles et les appellera via le protocole MCP.
|
Flux de travail : Comment utiliser MCP
Mode 1 — Interaction avec votre instance DHIS2
Chaque session nécessite de se connecter d'abord à une instance DHIS2 spécifique :
- Dites à l'IA de se connecter avec
dhis2_connect en fournissant l'URL de votre instance, votre nom d'utilisateur et mot de passe DHIS2
- Le serveur MCP stocke la session (liée à votre clé API)
- Tous les appels suivants utilisent cette session pour interagir avec votre instance
|
💡 Astuce : Vous pouvez fournir vos identifiants DHIS2 directement dans votre message à l'IA. Par exemple : "Connecte-toi à moninstance.dhis2.cloud avec utilisateur=admin et mot de passe=monpassword"
|
Mode 2 — Interaction avec votre compte YaLIM Cloud
Pour gérer vos instances via le portail YaLIM Cloud, aucune connexion DHIS2 n'est nécessaire. Votre clé API suffit :
- L'agent IA utilise votre clé API pour accéder à votre espace (namespace) uniquement
- Vous pouvez lister vos déploiements, vérifier leur état, consulter les journaux
- L'accès est strictement limité à vos propres instances — vous ne pouvez pas voir ou modifier les instances d'autres utilisateurs
|
Dépannage
"ERROR: DHIS2_MCP_KEY environment variable is required"
Configurez votre clé d'API : export DHIS2_MCP_KEY="ymcp_..."
"Timed out waiting for SSE session"
Le serveur distant est peut-être injoignable. Vérifiez :
curl -s https://mcp.yalim.cloud/healthz
# Devrait retourner : ok
|
L'appel d'outil retourne "authentication failed"
Votre clé d'API est peut-être invalide ou expirée. Demandez-en une nouvelle depuis le portail YaLIM Cloud.
Journaux du connecteur (Logs)
Tous les journaux du connecteur sont envoyés vers stderr (stdout est réservé au protocole MCP). Pour voir les journaux :
|
DHIS2_MCP_KEY="ymcp_..." python3 scripts/mcp-connector.py 2>connector.log
|
|
Architecture
Voici comment fonctionne l'interaction entre votre agent IA et le serveur MCP :
Votre Agent IA (Claude, Cursor)
↓ parle en langage naturel
Connecteur MCP (script Python sur votre ordinateur)
↓ traduit en requêtes MCP
Serveur MCP (mcp.yalim.cloud)
↓ selon votre demande :
• Mode Instance DHIS2 → Votre instance DHIS2 (moninstance.dhis2.cloud)
• Mode Portail YaLIM Cloud → Votre espace sur le portail DHIS2 (uniquement vos instances)
|
|
💡 Important : Votre clé API est automatiquement injectée dans chaque requête par le connecteur. Vous n'avez pas besoin de la mentionner dans vos messages à l'IA.
|
|
Guide de configuration locale pour le service MCP de YaLIM Cloud
Connecting AI agents to DHIS2 instances
|
|
MCP Server ·
Portal ·
DHIS2 Cloud
Part of the YaLIM ecosystem — Managed DHIS2 hosting.
Operated by YaLIM LLC.
|
|
