Termdat

🇨🇭 Part of the Swiss Public Data MCP Portfolio — open-source MCP servers connecting AI agents to Swiss public and open data. This is a private project. It is independent of any employer or institutional affiliation.

🏷️ termdat-mcp

Version CI License: MIT Python 3.10+ MCP Auth: none Portfolio

Official, validated Swiss administrative designations across DE / FR / IT / EN — with source references and validation status.

🇩🇪 Deutsche Version

Overview

MCP server for TERMDAT, the terminology database of the Swiss Federal Administration, maintained by the Federal Chancellery. It gives an AI agent the officially validated designations of Swiss authorities, departments and legal acts across DE / FR / IT / EN — with source references and validation status.

Discovered through i14y-mcp, which catalogues TERMDAT as data service ff0c37eb-2f7c-4ff6-996e-d22b77bf52fc.

What this is — and what it is not. TERMDAT is not a subject dictionary. It is a certified name-plate archive: it will not tell you what «Sonderpädagogik» means, but it will tell you the official name of the authority responsible for it, and what that authority is called in French.

Measured coverage (live, 2026-07-19, German search over the Terminus field):

Search term	Hits
Departement	20
Bildung	13
Verordnung	8
Schule	5
Behörde	4
Sonderpädagogik	3
Volksschule · Lehrperson · Schulleitung · Unterricht · Kindergarten	0

The thirteen «Bildung» hits are organisational names — Bildungsdirektion, Erziehungsdepartement, Departement für Volkswirtschaft und Bildung — not pedagogical concepts. Plan accordingly: this server is strong for authority naming, official titles and abbreviations, and largely silent on domain vocabulary.

Features

• Seven read-only tools over the official TERMDAT public v2 API.
• Official designations across DE / FR / IT / EN, with source reference and validation status on every response.
• Communication QA: check up to 25 terms in one call against validated designations.
• Vocabulary cache (24 h TTL) for the 140 collections and 23 classifications, with stale-serve fallback.
• Retry with exponential backoff (2/4/8 s); explicit MaxEntryCount to avoid silent truncation.
• Dual transport: stdio (local) and SSE (cloud).
• No authentication required — public, unauthenticated API (No-Auth-First).

🎯 Anchor demo query

«What are the official French and Italian names of the education directorates of the German-speaking cantons?»

Resolved with list_classifications → search_terms → translate_term.

Demo

Prerequisites

• Python 3.10+
• uv / uvx (recommended) or pip
• Network access to api.termdat.bk.admin.ch — no API key needed

Installation

uvx termdat-mcp

Claude Desktop (claude_desktop_config.json):

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

Quickstart

# Run locally over stdio (default transport)
uvx termdat-mcp

# From a checkout, without installing
PYTHONPATH=src python -m termdat_mcp

Configuration

All configuration is via environment variables. Defaults are safe for local use.

Variable	Default	Purpose
TERMDAT_MCP_TRANSPORT	stdio	Transport: stdio (local) or sse / streamable-http / http (cloud)
HOST	127.0.0.1	Bind host (SSE transport only). Loopback by default; set HOST=0.0.0.0 only inside a container
PORT	8000	Bind port (SSE transport only)
TERMDAT_MCP_CORS_ORIGINS	[]	SSE only: explicit allowed browser origins (default-deny; never a wildcard in production)
TERMDAT_MCP_LOG_LEVEL	INFO	structlog level (JSON to stderr)
TERMDAT_MCP_VOCAB_TTL	86400	Vocabulary cache TTL in seconds

Configuration is loaded once into a typed Settings object (pydantic-settings).

Cloud (Render / Railway):

TERMDAT_MCP_TRANSPORT=sse PORT=8000 termdat-mcp   # exposes /sse

Available Tools

Tool	Purpose
search_terms	Search TERMDAT with field flags, collection and classification filters
translate_term	Official equivalent of an administrative term in another national language
check_terms	Communication QA: check up to 25 terms against validated designations
get_entries	Fetch known entries by numeric ID
list_collections	The ~140 terminology collections (filter values)
list_classifications	The 23 subject classifications, e.g. BILD = education
api_status	Availability; never returns silently empty

All tools are annotated readOnlyHint: true, destructiveHint: false.

MCP primitives. This server uses only the Tools primitive. TERMDAT answers are live queries with no stable resource hierarchy to expose as Resources, and there are no server-authored Prompts. The seven tools are small and closely related, so they live in a single server.py rather than a tools/ package.

Architecture

┌─────────────────┐   stdio / SSE    ┌──────────────────────────┐
│  MCP host       │ ───────────────► │  termdat-mcp             │
│  (Claude, IDE)  │ ◄─────────────── │                          │
└─────────────────┘                  │  vocabulary cache (24 h) │
                                     │  140 collections         │
                                     │   23 classifications     │
                                     └────────────┬─────────────┘
                                                  │ httpx + retry (2/4/8 s)
                                                  ▼
                              https://api.termdat.bk.admin.ch/v2
                              ├── /Search          (SearchTerm + InLanguageCode)
                              ├── /Entry           (EntryIds)
                              ├── /Collection      (140 values)
                              └── /Classification  ( 23 values, incl. BILD)

Architecture decision

This server uses Architecture A (live API only), with caching limited to the two controlled vocabularies.

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

• The API publishes a complete OpenAPI 3.0.4 specification at /swagger/v2/swagger.json and declares no security schemes — unauthenticated access, No-Auth-First satisfied.
• Server-side search works properly, including 11 field flags and filters by collection and classification. There is no reason to mirror the database locally, and no bulk dump is offered.
• /Collection (140 entries) and /Classification (23 entries) change rarely and are needed to make filter arguments legible to an agent, so they are cached with a 24-hour TTL and a stale-serve fallback.

Consequences:

• Every search is a live call; provenance is live_api except for vocabulary lookups.
• Validation errors arrive as clean RFC 9110 payloads and are surfaced rather than swallowed.

Project Structure

termdat-mcp/
├── src/termdat_mcp/
│   ├── __init__.py
│   ├── __main__.py       # entry point; dual transport (stdio / SSE)
│   ├── client.py         # httpx client, retry, vocabulary cache
│   ├── models.py         # Pydantic models
│   └── server.py         # MCP tool definitions
├── tests/
│   ├── test_client.py    # offline, respx-mocked
│   └── test_live.py       # hits the real TERMDAT API
├── README.md
├── README.de.md
├── CHANGELOG.md
├── LICENSE
└── pyproject.toml

Safety & Limits

• Read-only. Every tool is annotated readOnlyHint: true, destructiveHint: false; the server never writes to TERMDAT.
• No credentials handled. The API is unauthenticated; the server stores and forwards no secrets.
• No silent empties. api_status and error paths surface failures instead of returning an empty result that looks complete.
• Truncation is explicit. MaxEntryCount is always sent and truncated is reported (see Known Limitations).
• Licence caution. TERMDAT content carries no licence statement; every response repeats this in source. Clarify terms with the Federal Chancellery before republishing downstream.
• Egress allow-list. Requests can only reach api.termdat.bk.admin.ch (HTTPS), enforced before every call by a frozen ALLOWED_HOSTS set — no user input can redirect egress. See docs/network-egress.md.
• Loopback by default. SSE binds to 127.0.0.1; 0.0.0.0 is an explicit container opt-in that warns on stderr. SSE also sets default-deny CORS, exposing only Mcp-Session-Id.
• Errors are masked. Upstream/internal error detail is logged to stderr (structlog JSON) and never returned to the model.
• Accepted risks (ADRs): DNS pinning (ADR 0001) and stateful load balancing (ADR 0002) are deliberately deferred — low risk for a single-instance, single-host, no-auth server.
• Container. A hardened, non-root Dockerfile is provided for SSE deployments.

Known Limitations

• Administrative scope only. See the coverage table above. check_terms returns not_found, never «incorrect», precisely because absence from TERMDAT is not evidence of error.
• MaxEntryCount has a silent default of ~25. Omitting it looks like a complete result set. This server always sends the parameter explicitly and reports truncated.
• CollectionIds / ClassificationIds have a silent default of VARIA. An ID-less /v2/Search covers one of 23 subject areas — the residual one — and reports the truncated result as a normal empty answer. This server sends the full classification set unless you narrow it explicitly. See issue #11.
• SearchTerm is Lucene, and matching is on whole words. «Quellensteuer» does not match «Quellensteuerverordnung»; «Quellensteuer*» does. *, ? and ~ are available — on an empty result, retry with a wildcard before concluding the term is absent.
• Field.* flags default to true where unsent. Terminus, Name, Abbreviation and Phraseology are on unless explicitly disabled, so a partial flag set can only widen a search. This server sends all eleven flags explicitly, which is what makes fields able to narrow.
• Multilingual variants are opt-in. Without OutLanguageCode, entries return German designations only. translate_term sets it for you.
• The public API exposes less than the website. Not a scope setting — a coverage limit of the source. For «Quellensteuer» the website lists 12 distinct entries and the API returns 7 at maximum recall (every language, all 11 fields, infix wildcard, all classifications and collections). The overlap is one entry, 447912. Fetching the missing IDs directly via /v2/Entry returns HTTP 200 with an empty body — they are not served at all, so no query can reach them. One exception, 1557, is served but carries status In Bearbeitung in a collection marked «(aufgehoben)», which suggests the search index covers validated entries while the website also shows drafts and repealed material. Consequence: absence from this server means absence from the API, not from TERMDAT. Verified 2026-07-30 with the entry IDs supplied by @dfch in issue #11; worth raising with the Federal Chancellery rather than working around.
• No licence statement. The I14Y catalogue record carries license: null. Clarify terms with the Federal Chancellery before republishing TERMDAT content downstream. Every response repeats this in source.
• Entry-level language coverage varies. Not every entry exists in all four languages; translate_term omits entries without a target-language variant rather than inventing one.

Live probe findings (2026-07-19)

Endpoint	HTTP	Status	Note
/swagger/v2/swagger.json	200	✅	OpenAPI 3.0.4, 132 KB, securitySchemes: []
/v2/Search	200	✅	requires SearchTerm, InLanguageCode, ReturnType
/v2/Entry	200	✅	requires EntryIds, InLanguageCode
/v2/Collection	200	✅	140 values
/v2/Classification	200	✅	23 values, incl. BILD (education)
/v2/ (root)	404	❌	no index; the I14Y record points here
InLanguageCode=deu / de-CH	400	❌	only two-letter ISO codes, case-insensitive

Probe note: a correction worth recording. An earlier probe concluded that OutLanguageCode filters the result set, because adding it appeared to drop all hits. It does not. Two variables had been changed at once — the parameter and the search term — and the term itself («Volksschule») genuinely has zero hits. Verified afterwards across four broad terms: result counts are identical with and without OutLanguageCode; the parameter is purely additive. A regression test (test_out_language_is_additive_not_filtering) now guards this.

Rule of thumb: change one variable per probe call, or the API will confess to a crime it did not commit.

Live probe findings (2026-07-27) — search scope

Reported in issue #11: «Quellensteuer» returned nothing while the TERMDAT website returned twelve hits. Three independent causes, in descending order of effect. Entry counts, InLanguageCode=DE:

Query	ID-less (=VARIA)	all 23 classifications	+ free-text fields	+ * wildcard
Quellensteuer	0	1	3	6
Pensionskasse	1	4	22	27

The first column is what this server sent before the fix. The VARIA default is the dominant term: it hid FINANZWESEN, RECHT and twenty other subject areas behind an answer that looked like a confident zero.

Probe note. The failure mode worth recording is not the count — it is that an under-scoped search is indistinguishable from a genuine absence. In the reported session the model read the empty result together with this server's own «absence usually means out of scope» caveat and invented a plausible explanation for a term that was in the database all along. A tool that narrows silently will be believed silently. Hence hint on empty results, and a caveat that now tells the model to retry rather than to conclude.

Project Phase

This server is in Phase 1 (read-only). All tools are annotated readOnlyHint: true / destructiveHint: false and only ever query the public TERMDAT v2 API — there are no write, send, or filesystem capabilities.

Phase	Scope	Status
1 — Read-only	Search, translate and check administrative designations	✅ current
2 — Write-capable	(none planned)	—
3 — Multi-agent	(none planned)	—

A transition to a later phase would require a re-audit and human-in-the-loop controls before any write-capable tool is added.

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.

Era	Revision	Who reaches it
initialize handshake	2024-11-05 … 2025-11-25	What today's clients speak. The server answers with the revision asked for, or with the 2025-11-25 ceiling when the request asks for something newer.
Per-request envelope	2026-07-28	A request carrying the 2026-07-28 _meta envelope opens a modern connection.

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. This server builds no ASGI app to send an initialize through, so the gate asserts the SDK constants rather than a measured response — the weaker form, named rather than left unsaid.

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.

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.

Testing

PYTHONPATH=src pytest tests/ -m "not live"   # offline, respx-mocked
PYTHONPATH=src pytest tests/ -m live         # hits the real API
python scripts/check_ruff_pin.py
ruff check src/ tests/ scripts/
ruff format --check src/ tests/ scripts/
python scripts/check_version_sync.py

Changelog

See CHANGELOG.md.

Contributing

Issues and pull requests are welcome. Please keep tools read-only, run ruff check and the offline test suite before submitting, and add a CHANGELOG.md entry under [Unreleased] for user-facing changes.

Maintainers: see PUBLISHING.md for the step-by-step PyPI release process (Trusted Publishing via GitHub Release).

Security

See SECURITY.md for the security posture, hardening controls, and how to report a vulnerability.

License

MIT for this server — see LICENSE. TERMDAT content remains subject to the Federal Chancellery's terms.

Author

Hayal Oezkan · github.com/malkreide

Credits & Related Projects

• Data: TERMDAT, Swiss Federal Chancellery (BK).
• Catalogue entry: I14Y data service ff0c37eb…
• Discovery server: i14y-mcp
• Portfolio index: swiss-public-data-mcp