MCP · OAuth 2.1 · Read-only

MCP tools reference

Humanity Centered Data exposes a Model Context Protocol (MCP) server so AI assistants like Claude, ChatGPT, and Cursor can query displacement data on your behalf. All tools are read-only and run as the signed-in user via Supabase OAuth 2.1.

Endpoint

https://zazsorezackhfiijkpki.supabase.co/functions/v1/mcp

Add this URL as a custom MCP server in your client. You will be redirected to sign in and approve access before the tools appear.

Available tools

list_crisis_countriesList crisis countries
get_country_profileGet country profile
get_displacement_trendGet displacement trend
search_articlesSearch articles

list_crisis_countries

List crisis countries

read-only

List countries currently classified as Active Crisis or Protracted Crisis, with headline displacement figures.

Inputs

Name	Type	Required	Description
limit	integer (1-50)	no	Max countries to return. Default 20.

Example call

{
  "limit": 3
}

Example response

{
  "countries": [
    {
      "id": "syria",
      "name": "Syria",
      "region": "MENA",
      "status": "Protracted Crisis",
      "population": "No current figure",
      "idps": "No current figure",
      "refugees_out": "No current figure",
      "refugees_in": "No current figure"
    },
    {
      "id": "sudan",
      "name": "Sudan",
      "region": "Africa",
      "status": "Active Crisis",
      "population": "No current figure",
      "idps": "No current figure",
      "refugees_out": "No current figure",
      "refugees_in": "No current figure"
    },
    {
      "id": "ukraine",
      "name": "Ukraine",
      "region": "Europe",
      "status": "Active Crisis",
      "population": "No current figure",
      "idps": "No current figure",
      "refugees_out": "No current figure",
      "refugees_in": "No current figure"
    }
  ]
}

get_country_profile

Get country profile

read-only

Return the full profile for a country (population, IDPs, refugee flows, humanitarian status). Accepts country id (e.g. 'syria') or name.

Inputs

Name	Type	Required	Description
country	string	yes	Country id (slug) or English name, e.g. 'syria' or 'Syria'.

Example call

{
  "country": "syria"
}

Example response

{
  "profile": {
    "id": "syria",
    "name": "Syria",
    "region": "MENA",
    "status": "Protracted Crisis",
    "population": "No current figure",
    "idps": "No current figure",
    "refugees_out": "No current figure",
    "humanitarian_needs": "No current figure",
    "hub_url": "https://humanitycentereddata.com/syria"
  }
}

get_displacement_trend

Get displacement trend

read-only

Return IDP, refugee, and people-in-need figures plus key humanitarian needs for a country hub. Supports yearly (reported end-of-year totals) or monthly granularity (linearly interpolated between annual reference points; each month flagged with `interpolated`). Figures in millions, sourced from UNHCR, IOM DTM, and OCHA HNO/HRP.

Inputs

Name	Type	Required	Description
country	string	yes	Country id or name. Supported: syria, ukraine, sudan, yemen, drc, afghanistan, ethiopia, somalia, nigeria, colombia, georgia.
granularity	'yearly' \| 'monthly'	no	Series resolution. Default 'yearly' returns reported end-of-year totals. 'monthly' returns a 12-per-year interpolated series with each point flagged interpolated: true when it is not an annual reference month.
region	string	no	Optional sub-national region slug or name (e.g. 'north-kivu', 'donetska', 'darfur'). Omit to receive the full list of available regions. National totals are always included.
site	string	no	Optional camp or settlement slug or name (e.g. 'al-hol', 'zamzam', 'bulengo'). Returns population time series, computed annual growth rate (CAGR), key needs, management, and status. Omit to receive the list of available sites.
include_yoy	boolean	no	When true, include year-over-year change summaries (absolute in millions and percent) for IDPs, refugees originating, and people in need at the national level, plus an overall trend summary. Defaults to false.
include_exports	boolean	no	When true, include an `exports` block with CSV strings and chart_json arrays for the yearly national series (and monthly / yoy / sub-national / site series when those are also requested). Chart JSON rows have a `period` label plus numeric fields ready for Recharts, Chart.js, or Vega-Lite. Defaults to false.

Example call

{
  "country": "drc",
  "region": "north-kivu"
}

Example response

{
  "trend": {
    "country": "drc",
    "name": "DR Congo",
    "granularity": "yearly",
    "units": {
      "idps": "millions",
      "refugees_out": "millions",
      "people_in_need": "millions"
    },
    "series": [
      {
        "year": 2022,
        "idps": 5.5,
        "refugees_out": 1,
        "people_in_need": 27
      },
      {
        "year": 2024,
        "idps": 6.3,
        "refugees_out": 1,
        "people_in_need": 25.4
      }
    ],
    "subnational_available": [
      "north-kivu",
      "south-kivu",
      "ituri"
    ],
    "subnational_methodology": "Sub-national figures are curated from country hub content and IOM DTM / OCHA HNO area reports, end-of-year totals in millions. Regional totals do not necessarily sum to the national figure.",
    "subnational_selected": {
      "requested": "north-kivu",
      "matched": {
        "region": "North Kivu province",
        "slug": "north-kivu",
        "admin_level": "admin1",
        "notes": "M23 offensive since 2022 drove large-scale displacement around Goma.",
        "series": [
          {
            "year": 2022,
            "idps": 2.1,
            "people_in_need": 3.7
          },
          {
            "year": 2023,
            "idps": 2.8,
            "people_in_need": 4.1
          },
          {
            "year": 2024,
            "idps": 2.8,
            "people_in_need": 4.2
          }
        ]
      }
    },
    "summary": "IDPs in DR Congo moved from No current figure in 2022 to No current figure in 2024 (rising)."
  }
}

search_articles

Search articles

read-only

Search Humanity Centered Data articles by keyword across title, excerpt, tags, and category. Optionally filter by country slug.

Inputs

Name	Type	Required	Description
query	string	yes	Keyword to match.
country	string	no	Optional country slug filter, e.g. 'syria'.
limit	integer (1-25)	no	Max results. Default 10.

Example call

{
  "query": "camp conditions",
  "country": "syria",
  "limit": 2
}

Example response

{
  "count": 2,
  "results": [
    {
      "slug": "al-hol-camp-conditions-2026",
      "title": "Al-Hol Camp Conditions in 2026",
      "country": "syria",
      "category": "Analysis",
      "published_date": "2026-03-14",
      "url": "https://humanitycentereddata.com/syria/al-hol-camp-conditions-2026"
    },
    {
      "slug": "northeast-syria-idp-camps",
      "title": "Northeast Syria IDP Camps: Access and Aid",
      "country": "syria",
      "category": "Field Report",
      "published_date": "2026-02-02",
      "url": "https://humanitycentereddata.com/syria/northeast-syria-idp-camps"
    }
  ]
}

Prefer plain HTTP?

A subset of displacement data is also available via the public JSON API — no auth required.

View public API docs