Agent integrations

Tool · get_data_coverage

Return the latest available date and full time range for each map resolution (daily, monthly, annual) from the live manifest. Use this first to discover what date ranges are valid for get_gsat_series.

Parameters

None.

Example request

curl -X POST https://storylines.theclimatedatafactory.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_data_coverage",
      "arguments": {}
    }
  }'

Example response (structuredContent)

{
  "coverage": {
    "daily":   { "start": "1940-01-01", "end": "2026-07-14" },
    "monthly": { "start": "1940-01",    "end": "2026-06" },
    "annual":  { "start": "1940",       "end": "2025" }
  }
}

Tool · get_gsat_series

Return the GSAT time series for one storyline scenario at daily, monthly, or annual resolution. Each row contains a date (or year), absolute temperature t in °C, climatology clim, and anomaly anom relative to the 1991–2020 observed mean.

Parameters

Example request — recent observed monthly GSAT

curl -X POST https://storylines.theclimatedatafactory.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_gsat_series",
      "arguments": {
        "scenario": "observed",
        "resolution": "monthly",
        "start": "2024-01",
        "end": "2024-12",
        "limit": 12
      }
    }
  }'

Example response (structuredContent, truncated)

{
  "scenario": "observed",
  "resolution": "monthly",
  "count": 12,
  "rows": [
    { "date": "2024-01", "t": "13.14", "clim": "12.42", "anom": "0.72" },
    { "date": "2024-02", "t": "13.28", "clim": "12.55", "anom": "0.73" },
    { "date": "2024-03", "t": "13.47", "clim": "12.79", "anom": "0.68" }
    // …
  ]
}

Example request — annual +3 °C warming storyline

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_gsat_series",
    "arguments": {
      "scenario": "plus3",
      "resolution": "annual",
      "start": "2000",
      "end": "2025"
    }
  }
}

Tool · get_scenario_readouts

Return the three headline temperatures shown in the dashboard's HeadlineStat card (observed, preindustrial, +3 °C) for a single date. Defaults to the latest available date at the requested resolution.

Parameters

Example request

curl -X POST https://storylines.theclimatedatafactory.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "get_scenario_readouts",
      "arguments": { "date": "2024-06", "resolution": "monthly", "mode": "absolute" }
    }
  }'

Example response (structuredContent)

{
  "date": "2024-06",
  "resolution": "monthly",
  "mode": "absolute",
  "unit": "degC",
  "readouts": {
    "observed":      { "value": 13.42 },
    "preindustrial": { "value": 12.73 },
    "plus3":         { "value": 14.55 }
  },
  "missing": []
}

Tool · compare_scenarios

Return the three scenario temperatures for a single date AND the three authoritative pairwise deltas — warming since pre-industrial (observed−PI), additional warming under +3 °C vs. today (+3−observed), and the full scenario span (+3−PI). Prefer this over computing deltas from get_scenario_readouts. Includes a one-sentence summary string suitable for direct quoting.

Parameters

Example request

curl -X POST https://storylines.theclimatedatafactory.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "tools/call",
    "params": {
      "name": "compare_scenarios",
      "arguments": { "date": "2026-07-14", "resolution": "daily" }
    }
  }'

Example response (structuredContent)

{
  "date": "2026-07-14",
  "resolution": "daily",
  "mode": "absolute",
  "unit": "degC",
  "readouts": {
    "observed":      { "value": 17.42 },
    "preindustrial": { "value": 16.10 },
    "plus3":         { "value": 19.55 }
  },
  "deltas": {
    "observed_minus_preindustrial": 1.32,
    "plus3_minus_observed": 2.13,
    "plus3_minus_preindustrial": 3.45
  },
  "missing": [],
  "summary": "On 2026-07-14 (daily, absolute), observed temperature is +17.42 °C; that is +1.32 °C vs. pre-industrial, and a +3 °C warming world would be +2.13 °C vs. today (+3.45 °C vs. pre-industrial)."
}

Tool · get_map_tile_url

Resolve the CDN URL of the WebP raster tile the dashboard renders for a given scenario, date, resolution, projection, and kind. Tiles are images (colored by the −30…+30 °C colorbar), not raw numeric arrays — use get_gsat_series for globally averaged values.

Parameters

Rendering: by default the tool returns only the URL — cheap and small. Pass include_image: true to also embed the tile in the response so the assistant can render it inline. This is the raw temperature raster; it does not include coastlines, colorbar, or the dashboard's date caption.

Example request

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "get_map_tile_url",
    "arguments": {
      "scenario": "observed",
      "resolution": "daily",
      "date": "2026-07-14",
      "kind": "anomaly",
      "projection": "equirect"
    }
  }
}

Example response (structuredContent)

{
  "url": "https://cdn.theclimatedatafactory.com/maps/equirect/factual/tas/anomaly/daily/2026-07-14.webp?v=…",
  "scenario": "observed",
  "resolution": "daily",
  "kind": "anomaly",
  "projection": "equirect",
  "date": "2026-07-14",
  "grid": {
    "width": 1441,
    "height": 721,
    "registration": "node",
    "lonRange": [-180, 180],
    "latRange": [-90, 90]
  }
}

Tool · get_dashboard_link

Build a canonical dashboard URL that deep-links to a specific date, resolution, display mode, and view. All parameters are optional; only provided fields are added to the query string.

Parameters

Example response (structuredContent)

{
  "url": "https://storylines.theclimatedatafactory.com/?date=2026-07-14&res=daily&mode=anomaly&view=map",
  "params": {
    "date": "2026-07-14",
    "resolution": "daily",
    "mode": "anomaly",
    "view": "map"
  }
}

Errors

Tool-level errors are returned as an MCP tool result with isError: true and a human-readable message in content[0].text. Common cases:

• Invalid "start" for resolution="…": expected YYYY-MM-DD — date shape mismatched the requested resolution.
• "start" (…) must be on or before "end" (…) — range is inverted.
• Rate limit exceeded. Retry in Ns. — more than 30 calls in the last minute from your IP.
• CSV fetch failed: HTTP … or Manifest fetch failed: HTTP … — upstream data source was unavailable.

Discovery

MCP clients can enumerate tools with the standard tools/list JSON-RPC method against the same endpoint. Most clients (Claude Desktop, ChatGPT connectors, Cursor, Codex) do this automatically when you add the URL above as a remote MCP server.