🇨🇭 Part of the Swiss Public Data MCP Portfolio

discover-swiss-mcp

MCP server for discover.swiss Infocenter Open — search Swiss tourism data with per-object attribution

🇩🇪 Deutsche Version

Status

pre-release — search entitlement confirmation from discover.swiss: pending.

The live probe of 2026-09-17 found that /search works for the Open subscription — full text, distance ranking, date filters, 31 facets — although the official documentation states the opposite ("You can't use the search functionality"). The whole server is built on that endpoint, which makes the contradiction its main risk: an entitlement that contradicts the docs can be withdrawn without notice.

• Written confirmation from discover.swiss is a release gate. No release before that conversation has happened. Once it has, set DISCOVER_SWISS_ENTITLEMENT_CONFIRMED=YYYY-MM-DD and this section changes from pending to confirmed with that date.

• source_status reports the same state at runtime, so a host can see it without reading this file.

• If the entitlement is withdrawn, the server keeps answering through a narrower list fallback (see Architecture decision).

Release on hold (2026-09-26). The release step was started on 2026-09-26 and stopped at its precondition: no written confirmation from discover.swiss is on record. Held until it arrives: the PyPI and MCP-registry release of 0.1.0, the public reference instance (it would run on the operator's key, which the confirmation has to cover), the portfolio status change and gate G1 over a remote endpoint. Until then the server runs locally with your own key — see docs/DEMO.md.

Related MCP server: meteoswiss-mcp

Phases and gates

The server is read-only in every phase — no tool writes, and none will before a phase that says so explicitly. Each phase ends at a gate: what was built, what is open, and a decision to continue or to discard.

Anchor demo queries

Three questions this server is built to answer, chosen to fit the coverage it actually has. The tool chain for each — which tool, in which order, with which parameters — is in docs/DEMO.md, reproducible by anyone with a key.

1. City (Zurich pilot) — "I have a rainy day in Zurich — which museums are within walking distance of the main station, and where do I eat vegetarian afterwards?" search → get_details → search; Zürich Tourismus as the source (CC BY-SA), attribution visible.

2. Outdoor (Glarnerland) — "I'm in Braunwald: which hikes with little ascent are there, what does the webcam show right now, and is anything closed?" find_tours → webcams_near, together with swiss-tourism-mcp (closures, cable cars) and meteoswiss-mcp (weather). Shows two servers working together.

3. Lodging (nationwide) — "Family-friendly hotel near Interlaken, three stars, accessible — and how do I get there from Zurich airport?" find_accommodation with distance ranking → get_details, then swiss-transport-mcp for the journey.

Scope map

What the open index holds, counted live on 2026-09-17 (probes/PROBE_REPORT_discover-swiss-mcp.md). 20,817 objects in total.

explore_area and source_status report this coverage at runtime, so a model can check it before it searches.

Features

• 8 read-only tools over search, detail, accommodation, tours, events, webcams, area exploration and source status

• Per-object attribution — provider, licence and copyright notice travel in the response, not in this README

• Licence whitelist on the root license field; everything else is counted into excluded_by_license and never served

• Empty results carry a reason — a hint naming what to change, never an unexplained empty list

• Degraded states are named — quota_exhausted, upstream_unreachable, search_unavailable

• Dual transport — stdio (Claude Desktop) and Streamable HTTP (cloud)

Prerequisites

• Python 3.11, 3.12 or 3.13

• A discover.swiss Infocenter Open subscription key (self-service at portal.discover.swiss) — bring your own key

• Rate limits of that subscription: 60 calls/minute, 50,000 calls/month

Installation

git clone https://github.com/malkreide/discover-swiss-mcp.git
cd discover-swiss-mcp
pip install -e ".[dev]"

Usage / Quickstart

export DISCOVER_SWISS_KEY="your-subscription-key"

# stdio (Claude Desktop and other local clients)
python -m discover_swiss_mcp

# Streamable HTTP — binds to 127.0.0.1:8000 by default (localhost only)
DISCOVER_SWISS_MCP_TRANSPORT=streamable-http python -m discover_swiss_mcp

The key is read from the environment only. It is held as a secret value, is never written to a log line, and belongs in no file that gets committed. .env.example lists every variable with placeholders.

The HTTP transport answers only under its exact host:port. Binding to any other address than loopback is refused at start-up unless inbound OAuth and DISCOVER_SWISS_MCP_ALLOWED_HOSTS are configured — see SECURITY.md.

Container. A hardened image (non-root, read-only root filesystem, no capabilities) and Kubernetes manifests with an egress NetworkPolicy are in Dockerfile and deploy/k8s/; commands and a Claude Desktop configuration are in docs/network-egress.md.

Available Tools

All eight tools are read-only (readOnlyHint: true, openWorldHint: true). Every hit carries its own attribution; every response counts what it withheld (excluded_by_license, excluded_test_objects, excluded_by_default_types) and explains an empty result in hint.

Tool definitions are pinned in docs/tool-hashes.json; after an intended change, run python scripts/gen_tool_hashes.py --write in the same PR.

Attribution

Every response names its providers, and the host has to show them.

Each hit carries an attribution object — provider, licence and the provider's own copyright notice (for example «Zürich Tourismus www.zuerich.com», CC BY-SA). One result set can mix three licences: Zürich Tourismus (CC BY-SA), SchweizMobil (CC BY), TOMAS (CC BY-ND). A single licence line in a footer covers none of them correctly.

• Hosts and assistants: display provider and licence with the content taken from a hit. CC BY-SA content passed on stays CC BY-SA.

• CC BY-ND (no_derivatives: true, mostly TOMAS rooms): quote or state facts, never rewrite the description.

• Withheld objects (all rights reserved, no licence) are not served at all; excluded_by_license says how many there were.

The rules and the whitelist are in docs/LICENSES.md.

Architecture decision

ARCH A — live API only, search-centred, with a list fallback. (probes/PROBE_REPORT_discover-swiss-mcp.md, section 6)

• /search covers full text, type, place, distance, dates and facets in one endpoint. Seven of eight tools are views on it; /vertices/{id} serves the detail.

• There is no dump to mirror, and at 60 calls/minute and 50,000 a month a cache is enough: 15 minutes for search, 24 hours for detail. A monthly quota exhausted (403 with «quota») is a state — degraded: quota_exhausted — and is never retried.

• The risk is the entitlement. Search contradicts the documentation and can be withdrawn. On 401/403 from /search, search and find_accommodation fall back to the typed list endpoints with client-side locality and distance filtering, answer provenance: list_fallback, degraded: search_unavailable, and say in hint what they ignored. The fallback is deliberately narrow: no full text, no star/price/amenity filters, at most eight list calls per tool call.

• One project only: dsod-content. dsod-hs is a subset.

Known limitations

The twelve findings of the live probe that shape how this server behaves (probe report, section 10; details in CHANGELOG.md):

1. The documentation denies search; the API grants it. Release gate: written confirmation.

2. The documented example project demo-web answers 400. Projects come from /projects.

3. Paging is nextPageToken, not continuation. Field names from live answers, not from the docs.

4. top=1000 does not mean 1000. Cosmos DB cuts at ~4 MB; the token is followed.

5. An open product is not an open licence. All-rights-reserved and unlicensed objects are withheld and counted.

6. ds-containedInPlaceFilter is not a filter. It trims the response; the hit filter is the query parameter.

7. Schweiz Tourismus already supplies data (2,769 hotels) — the open channel carries their content.

8. Misspelt facet names are dropped silently — an invented one fails the whole request with 400. Only the eight verified names are sent; anything else is reported in missing_facets.

9. One hotel weighs 78 KB. get_details trims to ~8 KB.

10. There is test data in the production index. «Demo Event» is withheld and counted in excluded_test_objects.

11. Descriptions are HTML with entities. Resolved to plain text server-side.

12. Half the index is rooms and meeting rooms. search excludes them unless asked.

Configuration

Project Structure

discover-swiss-mcp/
├── src/discover_swiss_mcp/
│   ├── __main__.py        # python -m entry point, transport chosen by env
│   ├── server.py          # MCP server, lifespan, tool wrappers
│   ├── tools.py           # the *_impl functions, input and output models
│   ├── config.py          # settings from env; the key is a SecretStr
│   ├── models.py          # the response envelope
│   ├── licenses.py        # licence whitelist, attribution, test-object filter
│   ├── transform.py       # HTML to text, detail trimming
│   ├── net.py             # SSRF guard, DNS pinning, egress allow-list
│   ├── client.py          # API client: rate limit, retries, budget, cache, list fallback
│   ├── http_app.py        # HTTP transport: bind policy, Host/Origin lists
│   ├── auth.py            # inbound OAuth: scopes, token introspection, 401/403
│   ├── _version.py        # the package version, a leaf module
│   └── logging_config.py  # structlog, JSON to stderr
├── tests/                 # unit tests; test_live.py is the `live` marker, not run by CI
├── probes/                # live probe: scripts, raw responses, report
├── audits/                # audit reports (mcp-audit)
├── deploy/k8s/            # Deployment, NetworkPolicy, CiliumNetworkPolicy
├── docs/                  # LICENSES, DEMO, DEFAULTS, network-egress, tool-hashes.json
├── scripts/               # repo validation, release gate, tool hashes, default matrix
└── Dockerfile             # hardened image, base pinned by digest

Testing

# What CI runs — no network
pytest -m "not live"
ruff check .
ruff format --check .
python scripts/validate_repo.py .
python scripts/default_matrix.py --check     # docs/DEFAULTS.md matches the spec
# secrets over the whole history (what the CI job runs)
docker run --rm -v "$PWD:/repo" ghcr.io/gitleaks/gitleaks:v8.30.1 git /repo --config /repo/.gitleaks.toml --redact

# Live canaries — real API, key from the environment, never in CI
export DISCOVER_SWISS_KEY="your-subscription-key"
pytest -m live -rA

The live canaries (tests/test_live.py, about twenty calls) hold each tool to roughly half of what the index held on 2026-09-17 — «Landesmuseum» ≥ 20 hits, hotels ≥ 2,000, webcams within 100 km of St. Gallen ≥ 30, and so on — and check that scope parameters take effect: match="name" narrows, containedInPlace/id comes back as a facet, the Landesmuseum description arrives without HTML entities, the nearest hotel to Interlaken is in Interlaken. A floor that fails means a tool stopped finding what is there. Without a key the module skips; a skip is not a pass.

Changelog

See CHANGELOG.md

Contributing

Contributions are welcome — see CONTRIBUTING.md.

Security

Please report vulnerabilities as described in SECURITY.md.

License

MIT License — see LICENSE

The software is MIT. The data is not: it stays under the licence of the provider named in each hit. See docs/LICENSES.md.

Author

Hayal Oezkan · malkreide

Credits & Related Projects

• Data: discover.swiss Infocenter Open — data by the providers named per object

• Protocol: Model Context Protocol — Anthropic / Linux Foundation

• Conventions: openlex-mcp — reference implementation of this portfolio

• Portfolio: Swiss Public Data MCP Portfolio