I14y MCP

Part of the [Swiss Public Data MCP Portfolio](https://github.com/malkreide/swiss-public-data-mcp) — a collection of open-source MCP servers connecting AI agents to Swiss public and open data.

This is a private project. It is not affiliated with, endorsed by, or operated on behalf of any employer or public authority.

i14y-mcp

MCP server for the I14Y interoperability platform — Switzerland's national metadata catalogue.

🇩🇪 Deutsche Version

---

Why this server exists

The other servers in this portfolio answer *«what does the data say?»*. This one answers the question that comes first: «who publishes data on this topic, through which interface, under which licence?»

I14Y is the national data catalogue maintained by the Federal Statistical Office. It describes datasets, registered APIs, public services and harmonised concepts from the Confederation, cantons and communes, using the DCAT-AP-CH profile (eCH-0200).

Mnemonic: «Catalogue before shelf.» Without a catalogue, an agent has to

already know a data source exists. With one, it can find it.

---

🎯 Anchor Demo Query

*«Which authority publishes data on special needs education, through which

interface is it available, and under which licence?»*

search_catalog(query="Sonderpädagogik")

→ «Statistik der Sonderpädagogik» — Federal Statistical Office (BFS), theme: Bildung

get_dataset(dataset_id=...) → 2 distributions, licence: «Opendata BY ASK — attribution required, commercial use only with permission from the data supplier» → contact: auskunftsdienst@bfs.admin.ch

Two tool calls turn a vague topic into a named authority, a download URL and a licence you can act on — get_dataset aggregates the distributions, licences and contact point into one record.

Demo

---

Architecture

                 ┌──────────────────────────────┐

│ MCP Host (Claude) │ └───────────────┬──────────────┘ │ stdio | streamable-http ┌───────────────▼──────────────┐ │ i14y-mcp │ │ ┌────────────────────────┐ │ │ │ server.py (13 tools) │ │ │ ├────────────────────────┤ │ │ │ mappers.py │ │ DCAT → flat, one language │ ├────────────────────────┤ │ │ │ models.py (Pydantic) │ │ source + provenance envelope │ ├────────────────────────┤ │ │ │ client.py │ │ retry 2s/4s/8s, no-retry 4xx │ └────────────────────────┘ │ └───────────────┬──────────────┘ │ HTTPS, no auth ┌───────────────▼──────────────┐ │ api.i14y.admin.ch/api │ │ datasets · dataservices · │ │ concepts · publicservices · │ │ catalogs · agents · search │ └──────────────────────────────┘

Architecture decision

This server uses Architecture A (live API only).

Rationale (verified live on 2026-07-21):

• All read endpoints respond without authentication and paginate correctly.
• No bulk download of catalogue metadata is offered, and none is needed.
• Error responses follow RFC 7807, so failure modes are distinguishable.

Consequences:

• Every HTTP call retries transient failures with 2 s / 4 s / 8 s backoff.
• search_catalog caps results client-side because the upstream ignores paging.
• api_status always returns an evaluable state instead of empty records.

Full probe report: docs/probe-i14y.md.

Project phase

This server is in Phase 1 (read-only) of the portfolio's «Read-only First» phase architecture: all tools are read-only, there is no authentication and no personal data. See docs/roadmap.md for the phase model and the prerequisites for any future write capability.

---

Tools

All tools are annotated readOnlyHint: true. Write operations exist in the upstream API but are deliberately not exposed.

MCP primitives

This server exposes Tools only — no Resources, no Prompts. That is a deliberate choice, not an omission: I14Y is queried by free-text search and by opaque UUIDs, so there is no small, stable set of addressable URIs that would map cleanly onto MCP Resources, and the server ships no opinionated prompt templates. Every tool is read-only and idempotent; if a future stable entry point emerges (e.g. a fixed theme list) it is a candidate for a Resource.

---

MCP Protocol Version

This server speaks two protocol eras over the same endpoint. The client's first request on a connection decides which one applies; a later claim from the other era is refused.

Both revisions are pinned in tests/test_protocol_version.py and asserted against the installed SDK, so a Dependabot bump of mcp cannot move either one silently. The handshake ceiling is measured against a live initialize through the assembled ASGI stack, not read off a constant name.

Note that the SDK's LATEST_PROTOCOL_VERSION is an alias for the modern era, not for the handshake era — pinning against it alone would leave the era that current clients actually negotiate free to drift.

What the server carries on the modern revision

2026-07-28 moves discovery off the initialize handshake onto server/discover plus a per-request _meta envelope, and gives every cacheable result a freshness hint. What this server puts on those surfaces is measured in tests/test_spec_2026_07_28.py through the assembled stack — and, for stdio, through a real subprocess — rather than read back off the configuration:

The freshness hint is not cosmetic. With none set, the SDK answers ttlMs: 0, cacheScope: private — «already stale, never share» — for directories that are fixed at import and cannot change while the process runs.

Both transports serve the modern revision: HTTP through the streamable-HTTP session manager, and stdio — the default, and what uvx i14y-mcp starts — through the same dual-era loop. Neither is evidence for the other, so both are measured.

One thing this server advertises but does not use. On 2026-07-28 the listChanged flags and resources.subscribe derive solely from whether subscriptions/listen is served, and the SDK wires that handler unconditionally. server/discover therefore reports listChanged: true for a tool list that is fixed at import, and a subscribe capability over an empty resource list; no change notification is ever sent. It is not switchable through the public API — only a wholesale replacement of the server/discover handler could do it, which would be a second truth about our own capabilities — so it is pinned by a test instead of papered over.

Update policy. When the gate fails, do not edit the constant blindly: read the spec changelog between the two revisions, verify the server still behaves, then move the constant, this section, README.de.md and CHANGELOG.md together.

---

Installation

uvx i14y-mcp

Or from source:

git clone https://github.com/malkreide/i14y-mcp

cd i14y-mcp pip install -e ".[dev]"

Claude Desktop

{

"mcpServers": { "i14y": { "command": "uvx", "args": ["i14y-mcp"] } } }

Remote deployment (Render, Railway)

I14Y_MCP_TRANSPORT=streamable-http HOST=0.0.0.0 PORT=8000 i14y-mcp

I14Y_MCP_TRANSPORT accepts stdio (the default of the entry point itself), streamable-http (http is a synonym) or sse. The HTTP transports bind to HOST, which defaults to 127.0.0.1 (loopback); set HOST=0.0.0.0 to expose the port on a PaaS (the container image already does both).

Connector URL: https:// /mcp

A Claude.ai custom connector speaks Streamable HTTP, and that transport serves exactly one path: /mcp. sse is the older transport and serves /sse and /messages instead — measured through the assembled app, POST /mcp answers 404 there and 200 under Streamable HTTP. The container image therefore defaults to streamable-http; a connector pointed at an SSE deployment gets a 404 and never completes a handshake.

I14Y_MCP_ALLOWED_HOSTS — required for a public deployment

A comma-separated list of the hostnames the server is reached under — hostnames only, no scheme and no port:

I14Y_MCP_ALLOWED_HOSTS=i14y-mcp.up.railway.app,mcp.example.ch

The value is compared literally against the incoming Host header, so https://i14y-mcp.up.railway.app or a trailing :443 matches nothing and every request fails with HTTP 421 Invalid Host header. Behind TLS the browser sends the bare hostname; a non-standard port needs the SDK's only wildcard form, host:*. Loopback stays reachable either way, so container health checks are unaffected.

Leaving it unset on a non-loopback bind does not fall back to something safe. The server cannot guess the name it will be addressed by, and a guessed list would reject every real request, so it switches the Host check off entirely and says so in the log:

dns_rebinding_protection_off

railway.json

railway.json pins the one build setting the deployment cannot get wrong on its own:

{ "build": { "builder": "DOCKERFILE", "dockerfilePath": "Dockerfile" } }

With any other builder Railway never looks at the Dockerfile. It derives a start command