ireland-mcp

# Ireland MCP

[![CI](https://github.com/c-mongan/ireland-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/c-mongan/ireland-mcp/actions/workflows/ci.yml)
[![Licence: MIT](https://img.shields.io/badge/licence-MIT-34c08a.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Streamable%20HTTP-6f42c1.svg)](https://modelcontextprotocol.io)
[![Token budget](https://img.shields.io/badge/default%20surface-7%20tools%20%7C%20~2.1k%20tokens-0a7.svg)](#why-its-lean)

**Ireland MCP is a free, read-only MCP server that lets AI assistants answer questions with live Irish public data and citations.**

Hosted endpoint: `https://mcp.irishopendata.ie/mcp` (origin fallback: `https://func-ireland-mcp-aofsjpwgy4hva.azurewebsites.net/mcp`)
Transport: Streamable HTTP. Auth: none. Writes: none.
Website: <https://irishopendata.ie> (canonical). `https://irishopendata.com` and `https://mcp.irishopendata.com/mcp` remain working aliases; see [docs/domain-go-live.md](docs/domain-go-live.md).
Registry: [`io.github.c-mongan/ireland-mcp`](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.c-mongan%2Fireland-mcp/versions/latest) on the official MCP Registry.
<!-- counts:start (generated by `npm run counts`; CI checks it) -->
| Count | Value | Definition |
| --- | ---: | --- |
| Data sources | 29 | Upstream public-data sources, one module each. The `cross` combiner is not a source. |
| Working on the hosted endpoint | 28 of 29 | NTA realtime needs an operator key that the hosted service does not have. |
| Catalogue operations | 74 | 71 source operations plus 3 cross-source ones (`list_sources`, `nearby`, `ireland_snapshot`), all callable through `ireland_call`. |
| Default tools | 7 | What `tools/list` returns: 4 meta tools plus `search`, `fetch` and `nearby`. |
| Tools with `?toolsets=all` | 80 | Every operation as a typed tool, plus the 4 meta tools, `search` and `fetch`. |
| Prompts | 3 | `area_profile`, `commute_check`, `compare_counties`. |
<!-- counts:end -->

## Try it in 60 seconds

1. Add the server to your client. For GitHub Copilot CLI:
   `copilot mcp add --transport http ireland https://mcp.irishopendata.ie/mcp`
   For VS Code, add `.vscode/mcp.json`: `{ "servers": { "ireland": { "type": "http", "url": "https://mcp.irishopendata.ie/mcp" } } }`.
2. Ask: *"Using the ireland MCP tools, give me the Census 2022 profile of Ennis, Co Clare, and the Met Éireann forecast for Galway. Cite the sources."*
3. Check the answer cites `https://data.cso.ie/table/F1015` and the Met Éireann location-forecast URL. The forecast URL is `http://`; Met Éireann's `https://` host currently redirects to an origin that fails TLS.

<p align="center">
  <img src="docs/demo/inspector.gif" alt="MCP Inspector calling the hosted endpoint: nearby Galway, CSO profile for Ennis, Met Éireann forecast and Property Price Register stats, each with a source citation" width="800">
</p>

| Client (tested 7 Oct 2026 against the hosted endpoint) | Result |
| --- | --- |
| MCP Inspector (Playwright, [`scripts/demo-inspector.mjs`](scripts/demo-inspector.mjs)) | 4/4 calls (`nearby`, CSO, Met Éireann, PPR) returned data with citations. [CSO Ennis](docs/demo/inspector-cso-ennis.png), [PPR Galway 2024](docs/demo/inspector-ppr-galway-2024.png). |
| VS Code Insiders, Copilot agent mode | Census 2022 Ennis (27,923 people) and Galway forecast, with CSO and Met Éireann citations. [Screenshot](docs/demo/vscode-copilot-chat.png). |
| GitHub Copilot CLI | 3/3 questions answered with citations: Met Éireann Galway, PPR Cork, CSO Ennis. [Evidence](docs/demo/README.md). |
| Every catalogue operation | <!-- live-ops:start -->[docs/live-all-ops.md](docs/live-all-ops.md) (2026-10-08): 72 of 74 pass, 0 fail; 2 need the NTA key.<!-- live-ops:end --> |

How a call flows:

```mermaid
flowchart TD
  Q[Client question] --> T[ireland_call / nearby / search]
  T --> V[Schema validation]
  V --> C{Cache hit?}
  C -- yes --> E[Evidence envelope]
  C -- no --> B{Circuit breaker open?}
  B -- yes --> S{Stale cache available?}
  B -- no --> U[Upstream public API: CSO, Met Éireann, PPR, ...]
  U -- ok --> E
  U -- 5xx or timeout --> R[One jittered retry]
  R -- ok --> E
  R -- still failing --> S
  U -- other error --> S
  S -- yes --> F[Stale cached result: stale=true]
  F --> E
  S -- no --> X["MCP error: isError=true, UPSTREAM_DOWN with hint; no cited result"]
  E --> A[Answer with source URL, licence, attribution, retrieved_at]
```

<p align="center">
  <a href="docs/architecture/ireland-mcp-arch-v5.drawio">
    <img src="docs/architecture/ireland-mcp-arch-v5.png" alt="Ireland MCP architecture: clients, Azure Functions gateway, observability and public data sources" width="900">
  </a>
</p>

## Try asking

- “What is the latest population profile for Galway city or County Cork?”
- “Are there Met Éireann weather warnings near Dublin today?”
- “What did houses sell for in Ennis last year?”
- “When is the next train from Heuston, and are there disruptions?”
- “Who are the current TDs for my constituency, and what bills are active?”
- “What protected habitats, monuments, planning applications or census areas are near this point?”

## See it work

| Proof | Screenshot |
| --- | --- |
| Live landing page, desktop | <img src="docs/screenshots/landing-desktop.png" alt="Ireland MCP live landing page on desktop" width="360"> |
| Live landing page, mobile | <img src="docs/screenshots/landing-mobile.png" alt="Ireland MCP live landing page on mobile" width="180"> |
| Install section with one-click client setup | <img src="docs/screenshots/install-section.png" alt="One-click install section for VS Code, Cursor, Claude, ChatGPT and Copilot CLI" width="360"> |
| Playground populated from a real live MCP call | <img src="docs/screenshots/playground-live-call.png" alt="Playground showing a real cso_search_tables result from the live MCP endpoint" width="360"> |
| MCP Inspector connected to the live endpoint | <img src="docs/screenshots/mcp-inspector-live.png" alt="MCP Inspector showing tools/list and an ireland_call result" width="360"> |
| Real model transcript: question → tool calls → answer | <img src="docs/screenshots/agent-transcript.png" alt="Azure OpenAI agent transcript using Ireland MCP tools" width="360"> |

## Install

| Client | Current setup |
| --- | --- |
| Claude custom connector | Settings → Connectors → **Add custom connector** → URL `https://mcp.irishopendata.ie/mcp` → no auth. |
| ChatGPT developer mode connector | Settings → Apps & Connectors → Advanced settings → enable **Developer mode** → create MCP connector → URL above → no auth. The remote endpoint supports Streamable HTTP; `search`/`fetch` are included for deep-research style clients. |
| VS Code | Install link (paste into a browser or run `open` on it): `vscode:mcp/install?%7B%22name%22%3A%22ireland%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.irishopendata.ie%2Fmcp%22%7D`. Or add `.vscode/mcp.json`: `{ "servers": { "ireland": { "type": "http", "url": "https://mcp.irishopendata.ie/mcp" } } }`. |
| VS Code Insiders | Install link: `vscode-insiders:mcp/install?%7B%22name%22%3A%22ireland%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.irishopendata.ie%2Fmcp%22%7D`. |
| Cursor | Deeplink: [`cursor://anysphere.cursor-deeplink/mcp/install?name=ireland&config=...`](cursor://anysphere.cursor-deeplink/mcp/install?name=ireland&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vbWNwLmlyaXNob3BlbmRhdGEuaWUvbWNwIn0=). Decoded config: `{ "type": "http", "url": "https://mcp.irishopendata.ie/mcp" }`. |
| GitHub Copilot CLI | `copilot mcp add --transport http ireland https://mcp.irishopendata.ie/mcp` or put the JSON below in `~/.copilot/mcp-config.json`. |
| Claude Code | `claude mcp add --transport http ireland https://mcp.irishopendata.ie/mcp` |
| Local stdio | npm package target: `npx -y ireland-mcp` after npm publication. Today, run from source: `npm ci && npm run build && node dist/src/cli.js`. To list typed tools locally, run `node dist/src/cli.js --toolsets=cso,irish-rail` or `IRELAND_MCP_TOOLSETS=all node dist/src/cli.js` after building. |

Portable Copilot / MCP JSON:

```json
{
  "mcpServers": {
    "ireland": {
      "type": "http",
      "url": "https://mcp.irishopendata.ie/mcp",
      "tools": ["*"]
    }
  }
}
```

## Why it is lean

Most data MCPs expose every typed tool up front. Ireland MCP keeps the default `tools/list` to **7 tools, 8,407 characters, about 2,102 tokens** (`toolsets=all` is 80 tools, about 22k tokens) (`npm run measure:tools`). CI fails if that list grows past 16,000 characters.

<p align="center">
  <a href="docs/architecture/ireland-mcp-lean-surface.drawio">
    <img src="docs/architecture/ireland-mcp-lean-surface.png" alt="Token-cost comparison: 7 default tools versus all typed tools and one-server-per-source routing" width="800">
  </a>
</p>

Need typed tools anyway?

| Surface | Use |
| --- | --- |
| Default HTTP | `/mcp` lists only `ireland_catalogue`, `ireland_describe`, `ireland_call`, `ireland_about`, `search`, `fetch`, `nearby`. |
| Source toolsets | `/mcp?toolsets=cso,irish-rail` lists selected typed tools too. |
| One source path | `/mcp/x/{source}` lists that source's typed tools, for example `/mcp/x/met-eireann`. |
| Everything | `/mcp?toolsets=all` lists all available tools and is useful for debugging, not routine chat. |
| Local stdio | From source: `node dist/src/cli.js --toolsets=cso` or `IRELAND_MCP_TOOLSETS=all node dist/src/cli.js` (npm package not yet published). |

`max_tokens` defaults to about 2,000 output tokens and can be set from 100 to 8,000. Large results return `truncated`, counts and narrowing hints instead of flooding the context.

## Architecture

The server is a stateless Azure Functions Flex app with a lean gateway in front of the source modules. The gateway owns the operation index, response budgets, cache, upstream budgets, circuit breakers, one jittered retry for transient 5xx/timeout failures and evidence envelope; every normal resul