Termdat MCP

🇨🇭 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

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):

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 Streamable HTTP (cloud). Both serve MCP protocol revision 2026-07-28.
• 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.

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

List variables. TERMDAT_MCP_CORS_ORIGINS and TERMDAT_MCP_ALLOWED_HOSTS take a comma-separated list — the recommended spelling, and the one the rest of the Swiss Public Data MCP portfolio uses:

TERMDAT_MCP_ALLOWED_HOSTS="mcp.example.ch,mcp.example.ch:443"

A JSON list (["mcp.example.ch"]) stays valid. Surrounding whitespace and empty entries are dropped in both forms, so a trailing comma is harmless. A single value needs no brackets.

`TERMDAT_MCP_ALLOWED_HOSTS` matters in the cloud. The SDK leaves DNS-rebinding protection off while no allow-list is configured. Bind to 0.0.0.0 in a container without this variable and the Host header is never validated — the server cannot derive its own public name from the bind address, and a guessed list would reject every real request with HTTP 421. It warns on startup when it has to fall back to that state.

Cloud (Render / Railway):

TERMDAT_MCP_TRANSPORT=streamable-http PORT=8000 termdat-mcp   # exposes /mcp

Available Tools

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 / HTTP    ┌──────────────────────────┐

│ 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 / Streamable HTTP) │ ├── 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).
• Terms of use are stated, not guessed. Every response repeats them in source: reuse and republication require the source www.termdat.ch to be named, and the Federal Chancellery's Terminology Section to be informed of purpose and manner beforehand (statement of 2026-08-21).
• 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. The HTTP transport binds to 127.0.0.1; 0.0.0.0 is an explicit container opt-in that warns on stderr. It 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 hosted 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