.codex-plugin— mcp server

<div align="center"> <h1>@cyanheads/who-gho-mcp-server</h1> <p><b>Query WHO Global Health Observatory data — 3,059 indicators across 194 member states with country, region, year, and sex filters via MCP. STDIO or Streamable HTTP.</b> <div>6 Tools • 2 Resources</div> </p> </div>

<div align="center">

</div>

<div align="center">

Public Hosted Server: https://who-gho.caseyjhand.com/mcp

</div>

Tools

6 tools for working with WHO Global Health Observatory data:

who_search_indicators

Search the WHO GHO indicator catalog by keyword.

• Substring match on indicator names — try terms like "life expectancy", "immunization", "mortality", "diabetes", or "HIV"
• Returns indicator codes and display names for use with who_query_indicator_data
• Reports total matches; suggests narrowing when the limit is reached
• Default limit 20, max 100

who_list_indicators

Browse the full indicator catalog with offset-based pagination.

• No keyword required — lists all 3,059+ indicators
• Pagination via limit (default 50, max 500) and offset
• Returns total and hasMore for iteration

who_get_indicator_metadata

Fetch metadata for one to ten indicator codes in a single call.

• Returns the full indicator name and the dimension types it supports (e.g. COUNTRY, SEX, REGION, AGEGROUP)
• Call before who_query_indicator_data to confirm which filter dimensions are valid
• Unresolved codes are reported in notFound rather than raising an error

who_list_dimensions

List all dimension type codes available in the GHO API.

• Returns every dimension type with its human-readable title
• Common types: COUNTRY, REGION, SEX, WORLDBANKINCOMEGROUP, AGEGROUP
• Use to discover codes before calling who_list_dimension_values

who_list_dimension_values

List valid filter values for a single dimension type.

• Returns codes and labels for every value under the dimension (e.g. all 194 country ISO codes, all WHO region codes)
• Includes optional parent hierarchy fields (parentCode, parentLabel, parentDimension)
• Use to confirm exact codes before passing them to who_query_indicator_data

who_query_indicator_data

Query data rows for a single WHO GHO indicator.

• Spatial filters (mutually exclusive): country_codes (ISO 3166-1 alpha-3), region_codes (WHO regions), or income_group_codes (World Bank groups)
• Time range filter: year_from / year_to
• Sex filter: SEX_BTSX (both), SEX_FMLE, SEX_MLE — only applies when the indicator uses SEX as its first cross-cutting dimension
• Arbitrary dim1_value for indicators using non-SEX cross-cutting dimensions
• Optional uncertainty interval bounds (low/high) via include_uncertainty (default true)
• Default limit 200, max 1000; returns totalRows and truncated for handling large result sets
• Primary data tool in the find-then-query workflow

Resources

Recommended workflow

1. who_search_indicators — find indicator codes by keyword
2. who_get_indicator_metadata — confirm which filter dimensions the indicator supports
3. who_query_indicator_data — fetch data with country/region/year/sex filters

To look up filter codes: who_list_dimensions → who_list_dimension_values.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation
• Unified error handling across all tools
• Pluggable auth (none, jwt, oauth)
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase

WHO GHO-specific:

• Full coverage of the WHO GHO OData API v2 — indicators, dimensions, dimension values, and data queries
• Configurable base URL and request timeout for custom or mirrored deployments
• Parallel metadata fan-out for multi-code indicator lookups

Agent-friendly output:

• Tool descriptions encode the cross-tool workflow — agents discover the right call order from descriptions alone
• Structured truncation signaling (truncated, truncatedNote, hasMore) so agents can decide whether to paginate
• Discriminated error codes with recovery hints on every failure path

Getting started

Self-Hosted / Local

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "who-gho-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/who-gho-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "who-gho-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/who-gho-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "who-gho-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/who-gho-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.3.2 or higher (or Node.js ≥24).
• No API key required — the WHO GHO API is public.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/who-gho-mcp-server.git

1. Navigate into the directory:

cd who-gho-mcp-server

1. Install dependencies:

bun install

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:

Running the server

Local development

• Build and run the production version:

  # One-time build
  bun run rebuild

  # Run the built server
  bun run start:http
  # or
  bun run start:stdio

• Run checks and tests:

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for logging, ctx.state for storage
• Register new tools and resources in the createApp() arrays

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.