YaLIM Cloud MCP — Local Configuration Guide

Published on June 6, 2026 · YLIM Team

How to setup and use YaLIM Cloud MCP to manage your account and your DHIS2 instance

This guide explains how to connect an AI agent (Roo, Cline, Claude Desktop, Cursor, etc.) to the YaLIM Cloud MCP server.

Overview

The YaLIM Cloud MCP server is already deployed and available at https://mcp.yalim.cloud. It allows you to interact with your DHIS2 instances and your YaLIM Cloud account using an AI agent.

Two Interaction Modes

Mode 1 — Interact with your DHIS2 instance: The AI agent can connect to your DHIS2 instance and perform operations (list data, create organization units, import data, etc.). You need to provide your YaLIM Cloud portal API key and your DHIS2 instance credentials.

Mode 2 — Interact with your YaLIM Cloud account: The AI agent can manage your DHIS2 instances and other deployed applications (check status, view logs, restart). With your API key, access is limited to your own namespace on the YaLIM Cloud portal.

Mode

What you need

Example actions

DHIS2 Instance

API Key + DHIS2 Credentials

List data, create forms, import/export

YaLIM Cloud Account

API Key only

Check status, view logs, restart

How it works? AI agents communicate with the MCP server using a standard protocol. We provide a small script (connector) that enables your AI agent to communicate with the YaLIM Cloud MCP server hosted on our infrastructure.

In summary: Your AI agent talks to the connector → The connector talks to the MCP server → The MCP server talks to your DHIS2 instance or YaLIM Cloud account.

Prerequisites

Python 3.8+ (no additional packages required — uses only the standard library)
A YaLIM Cloud Portal API key (format: ymcp_...)

Getting an API Key

API keys are managed in the YaLIM Cloud Portal. Each key is tied to a user and provides access to DHIS2 instances within that user's namespace.

Quick Start

1. Configure your API key

              export DHIS2_MCP_KEY="ymcp_your_api_key_here"
            

2. Test the connector

              cd <extracted-folder>

              bash scripts/test-connector.sh

You should see the server respond with its list of tools (36 tools available).

3. Configure your AI tool

See the tool-specific sections below.

AI Tool Configuration

cursor / Roo / Cline

These tools read the .roo/mcp.json file at the project root:

{

  "mcpServers": {

    "dhis2": {

      "command": "python3",

      "args": ["scripts/mcp-connector.py"],

      "env": {

        "DHIS2_MCP_URL": "https://mcp.yalim.cloud",

        "DHIS2_MCP_KEY": "ymcp_your_api_key_here"

      }

    }

  }

}

Note: Place the scripts/ folder from the downloaded connector package in your project directory, then create or update the .roo/mcp.json file as shown above.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{

  "mcpServers": {

    "dhis2": {

      "command": "python3",

      "args": ["/full/path/to/scripts/mcp-connector.py"],

      "env": {

        "DHIS2_MCP_URL": "https://mcp.yalim.cloud",

        "DHIS2_MCP_KEY": "ymcp_your_api_key_here"

      }

    }

  }

}

Cursor

Edit .cursor/mcp.json at the project root (same format as Claude Desktop):

{

  "mcpServers": {

    "dhis2": {

      "command": "python3",

      "args": ["scripts/mcp-connector.py"],

      "env": {

        "DHIS2_MCP_URL": "https://mcp.yalim.cloud",

        "DHIS2_MCP_KEY": "ymcp_your_api_key_here"

      }

    }

  }

}

Any MCP-compatible tool (generic)

The connector is a standard MCP stdio server. Run it as a subprocess with these environment variables:

Variable Required Default Description

DHIS2_MCP_KEY Yes — Your API key ymcp_...

DHIS2_MCP_URL No https://mcp.yalim.cloud MCP server URL

Available Tools

Once connected, the AI agent can discover and call these tool categories:

DHIS2 Tools (36 tools)

Tool

Description

dhis2_connect

Connect to a DHIS2 instance (URL + credentials)

dhis2_system_info

Get system version and build information

dhis2_list_org_units

List organization units with filters

dhis2_create_org_unit

Create a new organization unit

dhis2_list_data_elements

List/search data elements

dhis2_create_data_element

Create a new data element

dhis2_list_datasets

List datasets

dhis2_list_categories

List categories

dhis2_list_indicators

List indicators

dhis2_search_metadata

Search any metadata type

dhis2_get_metadata_schema

Get metadata schema definition

dhis2_export_metadata

Export a metadata package

dhis2_get_data_values

Retrieve data values

dhis2_import_data_values

Import data values (supports dry-run)

dhis2_complete_dataset

Mark dataset registration as complete

dhis2_get_data_approval

Get data approval status

dhis2_validate_data

Run validation rules

dhis2_run_analytics

Run aggregate analytics query

dhis2_get_event_analytics

Event analytics query

dhis2_get_enrollment_analytics

Enrollment analytics query

dhis2_list_dashboards

List dashboards

dhis2_get_visualization

Get visualization details

dhis2_list_programs

List tracker/event programs

dhis2_list_tracked_entities

Search tracked entity instances

dhis2_create_tracked_entity

Create a tracked entity

dhis2_enroll_tracked_entity

Enroll in a program

dhis2_list_events

List events

dhis2_create_event

Create an event

dhis2_update_event

Update an event

dhis2_import_tracker_data

Bulk tracker data import

dhis2_get_system_settings

Get system settings

dhis2_run_maintenance

Trigger maintenance tasks

dhis2_get_audit_log

Get audit log entries

dhis2_list_users

List DHIS2 users

dhis2_get_sql_view

Execute a SQL view

dhis2_get_data_element

Get data element details

YaLIM Cloud Portal Management Tools (your space only)

These tools allow you to manage your DHIS2 instances via the YaLIM Cloud portal. Access is strictly limited to your own namespace:

Tool

Description

portal_list_instances

List all your DHIS2 instances in your space

portal_get_instance

Get details and status of one of your instances

portal_get_instance_health

Check if your instance is running properly

portal_get_instance_logs

View logs of your instance

portal_restart_instance

Restart your DHIS2 instance

portal_stop_instance

Stop your instance (to save resources)

portal_start_instance

Start a stopped instance

portal_get_instance_info

Get configuration information for your instance

🔒 Security: These tools are limited to your own space. You cannot view, modify, or delete instances belonging to other YaLIM Cloud portal users.

Example: Using from an AI Agent

Once configured, you can ask the AI agent things like:

Examples with your DHIS2 instance

              "Connect to romyt.dhis2.cloud and list all level 2 organization units"

              "Create a new organization unit called 'Test District' under Equatorial Guinea"

              "List all data elements containing 'vaccine'"

              "Export the metadata package for the malaria program"

Examples with your YaLIM Cloud account

              "Show me the status of my romyt instance"

              "Check if my DHIS2 instance is running properly"

              "Show the logs of my instance for the last 24 hours"

              "Restart my DHIS2 instance"

The AI agent will automatically discover available tools and call them via the MCP protocol.

Workflow: How to Use MCP

Mode 1 — Interact with your DHIS2 instance

Each session requires connecting to a specific DHIS2 instance first:

Tell the AI to connect using dhis2_connect by providing your instance URL, DHIS2 username and password
The MCP server stores the session (linked to your API key)
All subsequent calls use this session to interact with your instance

💡 Tip: You can provide your DHIS2 credentials directly in your message to the AI. For example: "Connect to myinstance.dhis2.cloud with user=admin and password=mypassword"

Mode 2 — Interact with your YaLIM Cloud account

To manage your instances via the YaLIM Cloud portal, no DHIS2 connection is needed. Your API key is sufficient:

The AI agent uses your API key to access your namespace only
You can list your deployments, check their status, view logs
Access is strictly limited to your own instances — you cannot view or modify other users' instances

Troubleshooting

"ERROR: DHIS2_MCP_KEY environment variable is required"

Configure your API key: export DHIS2_MCP_KEY="ymcp_..."

"Timed out waiting for SSE session"

The remote server may be unreachable. Check:

              curl -s https://mcp.yalim.cloud/healthz

              # Should return: ok

Tool call returns "authentication failed"

Your API key may be invalid or expired. Request a new one from the YaLIM Cloud portal.

Connector Logs

All connector logs are sent to stderr (stdout is reserved for the MCP protocol). To view logs:

              DHIS2_MCP_KEY="ymcp_..." python3 scripts/mcp-connector.py 2>connector.log
            

Architecture

Here's how the interaction works between your AI agent and the MCP server:

Your AI Agent (Claude, Cursor)
↓ speaks in natural language
MCP Connector (Python script on your computer)
↓ translates to MCP requests
MCP Server (mcp.yalim.cloud)
↓ based on your request:
• DHIS2 Instance Mode → Your DHIS2 instance (myinstance.dhis2.cloud)
• YaLIM Cloud Portal Mode → Your space on the DHIS2 portal (your instances only)

💡 Important: Your API key is automatically injected into every request by the connector. You don't need to mention it in your messages to the AI.

Local Configuration Guide for YaLIM Cloud MCP Service

Connecting AI agents to DHIS2 instances

MCP Server · Portal · DHIS2 Cloud

Part of the YaLIM ecosystem — Managed DHIS2 hosting.
Operated by YaLIM LLC.

Back to blog Get Started Free