Swiss Grounding

Try it live

Add it to an assistant in one line, e.g. Claude Code (other clients):

claude mcp add --transport http swiss https://swiss-grounding-mcp-542630986415.europe-west6.run.app/mcp

It scales to zero when idle, so the first request after a pause starts an instance (about 2 s; hybrid search follows about 10 s later, keyword search answers meanwhile). It is rate-limited per client, refuses browser origins and is checked every 6 hours. The hosted instance runs the code in this repository, which also runs locally.

How it works

[Architecture: an AI assistant sends one tool call to Swiss Grounding MCP, which picks one of 13 read-only tools, resolves the place, fetches official federal, cantonal and municipal data politely and returns one cited answer]

_{The example is sample question 3 of the challenge brief, answered by the live server.}

Ask a general-purpose assistant about Switzerland and it may answer for the wrong canton, from an outdated page or from a neighbouring country. Swiss Grounding MCP gives it the responsible authority's own data instead:

1. One tool call. The assistant picks one of 13 read-only tools. Places work as people write them: Genf, Ginevra, Genève, Schuls → Scuol, 8003, Bahnhofstrasse 1, Zürich.
2. The right authority. Answers come from the level that is responsible (federal office, canton or municipality), through a prebuilt index of 10,630 official pages (keyword + multilingual semantic search), live federal APIs and municipal open data.
3. Polite and resilient. robots.txt and terms of use are respected by default, requests are paced and cached, and when a source is down a dated copy is served or the source is named.
4. One cited answer. Every tool returns the same contract, with verbatim excerpts and one of five statuses that tell the assistant what to do:

Coverage

The declared scope: what the server answers, for which area, from which authority. Assistants can read it too, with the swiss_coverage tool.

Not covered, and known limits

• Anything outside Switzerland, e.g. the German Rundfunkbeitrag in Konstanz: the server says so.
• Cantons GR, BL and SH block or do not serve text to automated clients, so their cantonal pages are not in the index (ch.ch and federal pages still apply; read_official_page reports the block honestly). VS (7 pages), TI (45) and TG (52) are only partly indexed.
• Municipal web pages are indexed for the nine cities above (120–250 pages each; Lausanne 66, Thun 32). Zürich has only a few pages, Bellinzona and Fribourg none yet (the next refresh crawls Fribourg's own domain, ville-fribourg.ch). For other municipalities the server returns the official website and can read a given page live.
• Waste calendars exist only where municipalities publish open data; elsewhere the server says so and links the municipality. Holidays, premiums and place facts cover every municipality.
• Cantonal law texts, individual tax calculations and weather forecasts are not provided.
• School holidays come from OpenHolidays, which aggregates official lists. Where the index holds the responsible authority's own calendar (e.g. ge.ch, bern.ch, the school of Scuol), that page is cited first, with the EDK list and the municipality site alongside. Periods are labelled by school type where a canton publishes several (canton Bern: German- and French-speaking schools).
• Registering on arrival in Lausanne is weak: the city's residents' office page is not in the index.
• Cross-language questions: a question in another language than the place's pages first returns a language hint, not the page, and the assistant has to search again. In end-to-end runs of such a question (French, about Bern), Sonnet followed the hint and answered from Bern's page; Haiku did so in 1 of 4 runs.
• Search is keyword-based by default. With the optional semantic extra it is hybrid and also finds pages worded differently or written in another language, but still misses some (measured); Romansh is not covered by the embedding model.

Results

With and without this server. The same 28 questions (the 5 published samples, 12 of our own and the organisers' 11 practice cases), asked to Claude Code with Sonnet three ways that differ only in their tools:

With the server, answers also take half the calls and half the time of web search (1.2 vs 2.4 calls, 14 vs 28 s per question). Web search often reaches the right figure, but mixes in comparison sites, news and tourism pages and rounds official figures; without any tools the model mostly declines or answers from dated knowledge.

Across the evaluation setup: 2 MCP clients × 2 LLMs, on the 5 published sample questions plus 11 of our own (de/fr/it/rm/en, including ask-back, out-of-scope and not-covered cases), run of 2026-09-25:

On the organisers' practice pack: Sonnet 11/11, Haiku 10/11. Hybrid search finds an official page on the topic for 25 of 38 labelled questions (keyword only: 19), and passes off no wrong page for the 5 questions that have none. Every miss is listed in docs/evaluation.md.

Run it yourself

Requires uv (it installs Python 3.13). No API keys or credentials are needed for any source.

git clone https://github.com/Gastaan/swiss-grounding-mcp && cd swiss-grounding-mcpuv sync --extra semantic                                                  # dependencies, with hybrid searchuv run --extra semantic swiss-grounding-mcp                               # stdio (for local MCP clients)uv run --extra semantic swiss-grounding-mcp --transport http --port 8000  # HTTP: http://localhost:8000/mcpcurl localhost:8000/health                                                # "search": "hybrid (…)"

The prebuilt data (municipality register, health premiums, search index, passage vectors) ships in the repository, built by the scripts in scripts/ and refreshed weekly (how). The first start unpacks the index (~1 s) and downloads the small embedding model once (~240 MB, in the background: searches use keywords until it is ready). For a lighter install without hybrid search, drop --extra semantic from the commands and client configurations (what changes).

Docker: the published image (~1.4 GB, hybrid search and its model included) runs as an unprivileged user and never downloads anything at runtime.

docker run -p 8000:8000 ghcr.io/gastaan/swiss-grounding-mcp                # HTTP: http://localhost:8000/mcpdocker run -i --rm ghcr.io/gastaan/swiss-grounding-mcp --transport stdio   # for a client that starts the server

Or build it with docker build -t swiss-grounding-mcp .. When the port is reachable from outside a trusted network, add -e SGM_AUTH_TOKEN=<secret> (HTTP security). Without cloning (keyword search): uvx --from git+https://github.com/Gastaan/swiss-grounding-mcp swiss-grounding-mcp.

Connect an MCP client

Any client that speaks MCP over stdio or Streamable HTTP works. Tested with Claude Code, OpenCode, the MCP Inspector CLI and the FastMCP client, including the legacy initialize handshake (protocol 2025-06-18) and the stateless 2026-07-28 protocol. For the hosted server, add its /mcp URL as a remote (HTTP) server. For a clone, use absolute paths and replace /path/to/swiss-grounding-mcp. The server sends usage instructions to the client.

claude mcp add swiss -- uv run --extra semantic --directory /path/to/swiss-grounding-mcp swiss-grounding-mcpclaude mcp add --transport http swiss-http http://localhost:8000/mcp

{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "swiss": {"type": "local", "command": ["uv", "run", "--extra", "semantic", "--directory", "/path/to/swiss-grounding-mcp", "swiss-grounding-mcp"], "enabled": true, "timeout": 30000},    "swiss-http": {"type": "remote", "url": "http://localhost:8000/mcp", "enabled": false, "timeout": 30000}  }}

{"mcpServers": {"swiss": {"command": "/full/path/to/uv", "args": ["run", "--extra", "semantic", "--directory", "/path/to/swiss-grounding-mcp", "swiss-grounding-mcp"]}}}

{"servers": {"swiss": {"type": "stdio", "command": "uv", "args": ["run", "--extra", "semantic", "--directory", "/path/to/swiss-grounding-mcp", "swiss-grounding-mcp"]}}}

{"mcpServers": {"swiss": {"command": "uv", "args": ["run", "--extra", "semantic", "--directory", "/path/to/swiss-grounding-mcp", "swiss-grounding-mcp"]}}}

[!TIP] Give the client a request timeout of 30 s or more. OpenCode waits only 5 s by default, while a slow official source can take longer; the server ends every tool call within SGM_TOOL_TIMEOUT (30 s) with a clean source_error, so a client timeout of 30 s lets that answer arrive.

Configuration

Nothing needs configuring. Respecting robots.txt and terms of use is on by default and can be switched off:

Cache, timeouts, offline mode, bearer token, rate limit, allowed origins and logging are described in docs/configuration.md.

Documentation

• Response contract and tools: the JSON every tool returns, the five statuses, place handling, all 13 tools
• Configuration and operations: every setting, HTTP security, caching and source etiquette, monitoring, the hosted instance
• Search: keyword and semantic ranking, and its measured quality
• Evaluation: the challenge self-check, end-to-end runs and every known miss
• Development: architecture, data and its weekly refresh, adding a source, tests

_{Built for the Swisscom myAI challenge Swiss Grounding MCP at Swiss AI Weeks, Zurich 2026.}