# `worldbank__worldbank_list_countries`

**List World Bank Countries**

List countries and regional aggregates with metadata: ISO codes, region, income level, capital, and coordinates. Filter by region code (e.g. EAS, SSF, NAC) and income level (LIC, LMC, UMC, HIC). Aggregate entries are excluded by default, leaving individual countries only; set include_aggregates=true to also return region, income group, and world aggregate entities.

- Server: [World Bank](https://gateway.mcpharbor.dev/docs/servers/worldbank) (`dev.mcpharbor.gateway/worldbank`)
- Price per call: $0.0001 (100 micro-USD); only tools/call is charged
- Endpoint: `https://gateway.mcpharbor.dev/mcp` or `https://gateway.mcpharbor.dev/mcp/worldbank`
- Upstream tool: exposed by the provider; called through this gateway as `worldbank__worldbank_list_countries`
- Provider terms: <https://data.worldbank.org/summary-terms-of-use> (verified 2026-09-19)
- Upstream API documentation: <https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation>
- Rate limit: 500 requests per minute
- Attribution required: "The World Bank: Dataset name: Data source (if known)"; same acknowledgment must be passed to sub-licensees

## Parameters

- `include_aggregates` (boolean, optional): When true, includes regional, income-group, and world aggregate entries alongside individual countries. Default false (individual countries only). Default: `false`.
- `income_level` (string, optional): Filter by income group code: LIC (Low income), LMC (Lower middle income), UMC (Upper middle income), HIC (High income).
- `page` (integer, optional): Pagination page number (1-based). Default: `1`.
- `per_page` (integer, optional): Results per page (default: server default, max: 300).
- `region` (string, optional): Filter by World Bank region code. Valid codes: EAS (East Asia & Pacific), ECS (Europe & Central Asia), LCN (Latin America & Caribbean), MEA (Middle East & North Africa), NAC (North America), SAS (S...

## Example call

Request headers and body:

```http
POST /mcp HTTP/1.1
Host: gateway.mcpharbor.dev
Authorization: Bearer <your gateway API key>
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: worldbank__worldbank_list_countries
```

```json
{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/clientCapabilities": {},
      "io.modelcontextprotocol/clientInfo": {
        "name": "example-agent",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/protocolVersion": "2026-07-28"
    },
    "arguments": {
      "include_aggregates": true
    },
    "name": "worldbank__worldbank_list_countries"
  }
}
```

A successful response:

```json
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "_meta": {
      "dev.mcpharbor.gateway/call": {
        "chargedMicroUsd": 100,
        "id": "<the id of this charge>"
      }
    },
    "content": [
      {
        "text": "<whatever the upstream tool returned>",
        "type": "text"
      }
    ],
    "resultType": "complete"
  }
}
```

This call costs $0.0001 (100 micro-USD). Reading this page and listing the tool cost nothing.
The `dev.mcpharbor.gateway/call` record in the result is the receipt for that charge. Each
POST is metered separately, so sending the same call again buys another one: see
[agent.txt](https://gateway.mcpharbor.dev/agent.txt), section 7, before retrying.

## Attribution

This provider requires the attribution below wherever you use results from its tools.
Reproduce it verbatim:

> "The World Bank: Dataset name: Data source (if known)"; same acknowledgment must be passed to sub-licensees

## Tool definition

Exactly as `tools/list` returns it (free):

```json
{
  "_meta": {
    "dev.mcpharbor.gateway/pricing": {
      "currency": "USD",
      "pricePerCallMicroUsd": 100
    }
  },
  "annotations": {
    "idempotentHint": true,
    "openWorldHint": true,
    "readOnlyHint": true
  },
  "description": "List countries and regional aggregates with metadata: ISO codes, region, income level, capital, and coordinates. Filter by region code (e.g. EAS, SSF, NAC) and income level (LIC, LMC, UMC, HIC). Aggregate entries are excluded by default, leaving individual countries only; set include_aggregates=true to also return region, income group, and world aggregate entities.",
  "inputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "include_aggregates": {
        "default": false,
        "description": "When true, includes regional, income-group, and world aggregate entries alongside individual countries. Default false (individual countries only).",
        "type": "boolean"
      },
      "income_level": {
        "description": "Filter by income group code: LIC (Low income), LMC (Lower middle income), UMC (Upper middle income), HIC (High income).",
        "type": "string"
      },
      "page": {
        "default": 1,
        "description": "Pagination page number (1-based).",
        "maximum": 9007199254740991,
        "minimum": 1,
        "type": "integer"
      },
      "per_page": {
        "description": "Results per page (default: server default, max: 300).",
        "maximum": 300,
        "minimum": 1,
        "type": "integer"
      },
      "region": {
        "description": "Filter by World Bank region code. Valid codes: EAS (East Asia & Pacific), ECS (Europe & Central Asia), LCN (Latin America & Caribbean), MEA (Middle East & North Africa), NAC (North America), SAS (South Asia), SSF (Sub-Saharan Africa).",
        "type": "string"
      }
    },
    "type": "object"
  },
  "name": "worldbank__worldbank_list_countries",
  "outputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "anyOf": [
      {
        "not": {
          "required": [
            "error"
          ]
        },
        "required": [
          "countries",
          "totalCount",
          "currentPage",
          "totalPages"
        ]
      },
      {
        "required": [
          "error"
        ]
      }
    ],
    "properties": {
      "countries": {
        "description": "Countries (and optionally aggregates) matching the filters.",
        "items": {
          "additionalProperties": false,
          "description": "A country or aggregate entry.",
          "properties": {
            "capitalCity": {
              "description": "Capital city name (empty for aggregates).",
              "type": "string"
            },
            "id": {
              "description": "Country or aggregate ID (ISO2 or WB aggregate code).",
              "type": "string"
            },
            "incomeLevel": {
              "additionalProperties": false,
              "description": "World Bank income classification.",
              "properties": {
                "id": {
                  "description": "Income level code.",
                  "type": "string"
                },
                "name": {
                  "description": "Income level name.",
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name"
              ],
              "type": "object"
            },
            "isAggregate": {
              "description": "True when this entry is a regional or income-group aggregate rather than an individual country.",
              "type": "boolean"
            },
            "iso2": {
              "description": "ISO2 country code.",
              "type": "string"
            },
            "latitude": {
              "description": "Capital latitude (empty for aggregates).",
              "type": "string"
            },
            "lendingType": {
              "description": "World Bank lending type classification.",
              "type": "string"
            },
            "longitude": {
              "description": "Capital longitude (empty for aggregates).",
              "type": "string"
            },
            "name": {
              "description": "Country or aggregate name.",
              "type": "string"
            },
            "region": {
              "additionalProperties": false,
              "description": "World Bank region this country belongs to.",
              "properties": {
                "id": {
                  "description": "Region code.",
                  "type": "string"
                },
                "name": {
                  "description": "Region name.",
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name"
              ],
              "type": "object"
            }
          },
          "required": [
            "id",
            "iso2",
            "name",
            "region",
            "incomeLevel",
            "lendingType",
            "capitalCity",
            "longitude",
            "latitude",
            "isAggregate"
          ],
          "type": "object"
        },
        "type": "array"
      },
      "currentPage": {
        "description": "Page number requested — past totalPages when the request ran off the end.",
        "type": "number"
      },
      "error": {
        "additionalProperties": {},
        "description": "Present when the call failed. Absent on success.",
        "properties": {
          "code": {
            "description": "JSON-RPC error code for this failure.",
            "maximum": 9007199254740991,
            "minimum": -9007199254740991,
            "type": "integer"
          },
          "data": {
            "additionalProperties": {},
            "properties": {
              "reason": {
                "description": "Machine-readable failure mode. Declared by this tool: `invalid_filter`: An invalid region or income_level code was provided. Other values are possible when a failure originates below the handler.",
                "examples": [
                  "invalid_filter"
                ],
                "type": "string"
              },
              "recovery": {
                "additionalProperties": {},
                "description": "Actionable next step for the caller.",
                "properties": {
                  "hint": {
                    "type": "string"
                  }
                },
                "required": [
                  "hint"
                ],
                "type": "object"
              },
              "retryable": {
                "description": "Whether retrying may succeed.",
                "type": "boolean"
              }
            },
            "type": "object"
          },
          "message": {
            "description": "Human-readable description of what went wrong.",
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "type": "object"
      },
      "notice": {
        "description": "Context for an empty page: which filters matched nothing, or the page range that exists when the requested page is past the end.",
        "type": "string"
      },
      "totalCount": {
        "description": "Total matching entries before pagination (includes aggregates if include_aggregates=true).",
        "type": "number"
      },
      "totalPages": {
        "description": "Total number of pages.",
        "type": "number"
      }
    },
    "type": "object"
  },
  "title": "List World Bank Countries"
}
```