MCP server

@worldscore/mcp gives any MCP client — Claude Desktop, Claude Code, or your own agent — read-only tools for sourced country scores. It ships no data: it's a thin client over the public API, so every answer carries the same provenance, tier, and reliability caution as the REST endpoints.

Install & configure

You need a free API key first (get one here). Then add this to your MCP client's config — no install step, npx fetches it:

{
  "mcpServers": {
    "worldscore": {
      "command": "npx",
      "args": ["-y", "@worldscore/mcp"],
      "env": { "WORLDSCORE_API_KEY": "wsk_your_key_here" }
    }
  }
}

Claude Desktop: Settings → Developer → Edit Config, paste the block, restart.
Claude Code: claude mcp add-json worldscore '{…}' or edit ~/.claude.json.
The key lives only in your config — the package never bundles it.

Tools

list_metrics

The full catalog: id, name, category, tier, direction, descriptive vs evaluative.

input

{}

output (trimmed)

{ "count": 82, "metrics": [ { "id": "gdp-per-capita-ppp",
  "name": "GDP per capita (PPP)", "confidenceTier": "A", "metricKind": "evaluative" }, … ] }

get_country_scores

Every metric score for one country, each with provenance, tier, and reliability caution.

input

{ "iso3": "ESP" }

output (trimmed)

{ "country": { "name": "Spain" }, "scoreCount": 82,
  "scores": [ { "metric": { "name": "GDP per capita (PPP)" }, "score": 79.83,
    "percentileRank": 82.6, "raw": { "value": 57965.29 }, "confidenceTier": "A",
    "provenance": { "source": { "name": "World Bank", "license": "CC BY 4.0" } } }, … ] }

get_metric_ranking

Full country ranking for a metric (best first). Pass crimeType for the crime family.

input

{ "slug": "government-effectiveness" }

output (trimmed)

{ "metric": { "name": "Government effectiveness" }, "coverage": { "withData": 204 },
  "ranking": [ { "name": "Singapore", "score": 100, "raw": { "value": 2.28 },
    "confidenceTier": "A", "provenance": { … } }, … ] }

compare_countries

2+ countries across metrics; each cell carries provenance and the score spread.

input

{ "countries": ["ESP","PRT","FRA"], "metrics": ["corruption-cpi"] }

output (trimmed)

{ "metrics": [ { "metric": { "name": "Corruption Perceptions Index" },
  "values": [ { "iso3": "ESP", "score": 56, "rank": 36 }, … ] } ] }

get_methodology

The scoring policy, confidence tiers, and normalization methods — so the model can explain a score.

input

{}

output (trimmed)

{ "policy": "Every score traces to a named, licensed source; missing = no data…",
  "tiers": { "A": "…", "B": "…", "C": "…", "D": "…" }, "methods": { … } }

Worked example: “which country has the cleanest government?”

An agent answers end-to-end, with provenance the user can check:

The model calls get_metric_ranking:

→ get_metric_ranking({ "slug": "government-effectiveness" })

The server calls the API with your key and returns the ranking with provenance:

← { "metric": { "name": "Government effectiveness" },
    "coverage": { "withData": 204 },
    "ranking": [ { "name": "Singapore", "score": 100, "raw": { "value": 2.28 },
      "confidenceTier": "A",
      "provenance": { "source": { "name": "World Bank (WGI)", "license": "CC BY 4.0" },
        "sourceYear": 2024 } }, … ] }

The model answers: “By the World Bank's Government Effectiveness indicator (2024, CC BY 4.0), Singapore ranks highest — but note this measures perceived state capacity, not corruption specifically; for corruption see the Corruption Perceptions Index.” — grounded, sourced, and honest about what the metric means.

What it ships (and doesn't)

The npm package contains only the client code — no data, no snapshots, no database, no pipeline. Those live in the private repo. Your API key stays in your local MCP config and is sent only to worldscore-pearl.vercel.app over HTTPS. Same rate limits as the API (1,000/day, 60/min).

← API documentation npm: @worldscore/mcp →