Gateway Oh

Kurz auf Deutsch. Dieses Gateway ist die eine Tür zu den Werkzeugen der Plattform OpenHelvetia: die Registry-Werkzeuge des Verzeichnisses und die beiden eingehängten Domänenserver über Fedlex (Bundesrecht, 35 Werkzeuge) und LINDAS (Politikdaten des Bundes, 8 Werkzeuge), zusammen 52 Fähigkeiten hinter einer Richtlinie: Sitzungsbudget, Ratenbegrenzung, typisierte Ablehnungen. Es läuft offline auf aufgezeichneten Antworten der Bundesendpunkte; nur der Live-Modus spricht mit dem Bund. Der Rest dieser Seite ist auf Englisch.

mcp-gateway-oh is the MCP gateway of the association OpenHelvetia. It serves one toolset over two doors, the Model Context Protocol streamable-HTTP transport at /mcp and a minimal JSON door (GET /tools, POST /tool/<capability id>), and it is the endpoint the association's own directory entry names and the citizen chat uses. This is the gateway that answers at https://mcp.openhelvetia.swiss/mcp and is listed in the official MCP Registry as swiss.openhelvetia/gateway.

What it is not. It is not a second implementation of anything. Every tool binds to the same domain functions that feed the platform's REST spine; the three mounted domain servers are the same crates published as mcp-fedlex-oh, mcp-lindas-politics-oh and mcp-i14y-catalogue-oh. The gateway adds the policy boundary, the flat namespace and the two-stage discovery, nothing else.

---

Contents

1. Before you start
2. Get it running in five minutes
3. Connect an MCP client
4. The policy: budget, rate limit, refusals
5. Command-line flags
6. The relay door
7. What is in this repository
8. How it is verified
9. When something does not work
10. Where this repository comes from
11. Contributing, security, licence

---

1. Before you start

You need three things. Nothing else.

Need	Why	How to get it
Rust, stable (rustc and cargo)	the gateway is a Rust program and is built from source	https://rustup.rs — one command, then open a new terminal and check with cargo --version
Git	to clone this repository	macOS: Xcode command-line tools (xcode-select --install); Linux: your package manager; Windows: https://git-scm.com
About 3 GB of disk and some minutes	the first build compiles the gateway, both domain servers and the auth profile once; later builds take seconds	—

Network: the tests and the fixture mode need none. Only the live mode talks to the Confederation's endpoints, with a polite brake of two requests a second per host.

2. Get it running in five minutes

git clone https://github.com/OpenHelvetia/mcp-gateway-oh.git
cd mcp-gateway-oh
cargo test --locked --manifest-path mcp/gateway/Cargo.toml

The suite runs the gateway end to end over both doors on the recorded fixtures; it ends with every test passing and no network. Then start the gateway offline, with the JSON door on port 8781 and the MCP door beside it:

cargo run --release --manifest-path mcp/gateway/Cargo.toml -- \
  --root . \
  --fedlex-fixtures mcp/servers/fedlex/tests/fixtures \
  --lindas-fixtures mcp/servers/lindas/tests/fixtures \
  --i14y-fixtures mcp/servers/i14y/tests/fixtures \
  --http 8781

In a second terminal:

curl -s http://127.0.0.1:8781/tools | head -c 600

curl -s -X POST http://127.0.0.1:8781/tool/fedlex.get_article \
  -H 'content-type: application/json' \
  -d '{"sr_number":"101","article":"8"}'

Every answer carries its provenance: the source, the date the fact was valid, the moment it was retrieved, and, for lists, whether the list was capped. Leave the two --*-fixtures flags away to run live against Fedlex and LINDAS.

3. Connect an MCP client

Over stdio, for a client that starts its servers itself (add the two fixture flags for an offline session):

{
  "mcpServers": {
    "openhelvetia": {
      "command": "cargo",
      "args": ["run", "--quiet", "--release", "--manifest-path", "mcp/gateway/Cargo.toml", "--", "--root", "."]
    }
  }
}

Over streamable HTTP, once the gateway runs with --http: point the client at http://127.0.0.1:8781/mcp. The live gateway of the association answers at https://mcp.openhelvetia.swiss/mcp the same way. tools/list is deterministic and flat, <domain>.<verb_object>; discovery is two-stage, meta.* first, then the domain's tools, so a client that was handed nothing but the URL finds everything.

4. The policy: budget, rate limit, refusals

Every tool method passes one gate before it does anything; both bounds are checked before either is charged, so a refusal changes nothing and costs nothing.

• The session budget (--budget <n>) is a hard weighted bound per session: registry reads weigh 1, domain calls 2. It does not recover with time. Absent, unlimited.
• The rate limit (--rate <n/min>, --burst <n>) is a token bucket per client, weighted the same way; the association runs 60 weight units a minute with a burst of 20. It recovers by itself, and the refusal says when. Absent, unlimited.
• The client is the process on stdio and the connection's source address on both HTTP doors, or the address a trusted edge wrote into a header (--client-ip-header, --trust-forwarded-for).
• Refusals are typed. rate-limited with retry_after_ms (HTTP 429 and Retry-After on the JSON door, a tool error on the MCP door), budget-exhausted, upstream-busy when the domain's brake declined to send and the charge is refunded, and the honest errors of the domain servers. A client renders them as what they are; nothing is padded.

5. Command-line flags

Flag	What it does
--root <dir>	the directory that holds registry/entries (this repository's root)
--budget <n>	per-session weighted budget; absent, unlimited
--rate <n/min>, --burst <n>	per-client rate limit; absent, unlimited
--upstream-rate <n/s>	the polite brake of both domain servers against their federal endpoints, default 2 with a burst of 4
--fedlex-fixtures <dir>, --lindas-fixtures <dir>, --i14y-fixtures <dir>	run the mounted domains offline on recorded fixtures
--http <port>	serve the JSON door and the MCP door on this port instead of stdio
--mcp-host <name>	a public host name the MCP door is served under, repeatable (DNS-rebinding guard)
--client-ip-header <name>, --trust-forwarded-for	how the client is keyed behind an edge or an ingress
--relay <name>[=<origin>]	open the relay door for one named provider, see §6
emit-inventory, emit-resource-metadata	print the discovery inventory and the RFC 9728 metadata; the drift gates compare them against the committed files

6. The relay door

One model provider the chat offers refuses browser calls (no CORS). For that provider only, the gateway opens /relay/<name>/<product>/…: it forwards the visitor's request with the visitor's own Authorization header to the provider's chat endpoint and model catalogue, returns the upstream's answer whole, stores nothing and logs nothing of the request, and admits nothing else, no other path, no other upstream, no call without a key. A relayed call is charged to the client's bucket like a domain call. Absent the flag, the door answers 404.

7. What is in this repository

Path	What it is
mcp/gateway/	the gateway crate: the policy gate, the two doors, discovery, the relay door, the end-to-end suite
mcp/gateway/tool-inventory.json	the two-stage discovery inventory, 52 capabilities, held against the code by a drift gate
mcp/gateway/oauth-protected-resource.json	the RFC 9728 protected-resource metadata, emitted from the capability register
mcp/gateway/server.json	the MCP Registry manifest of swiss.openhelvetia/gateway
mcp/servers/fedlex/, mcp/servers/lindas/, mcp/servers/i14y/, mcp/servers/common/	the three mounted domain servers and their shared crate, with their recorded fixtures
third_party/mcp-fedlex/	vendored upstream code the Fedlex server builds on, byte-identical, with its own copyright (PROVENANCE.md)
docs/reference/	the upstream rulebooks the servers are held against
registry/api/, profile/auth/, profile/org/	the API spine and the auth profile the gateway binds to; published on their own as api-spine-oh
registry/entries/	the directory entries the gateway serves
REUSE.toml, LICENSES/, publiccode.yml	licence metadata by path and the machine-readable description

8. How it is verified

cargo test --locked --manifest-path mcp/gateway/Cargo.toml runs the suite that holds the gateway's claims: the gate refuses before it charges, the budget is a hard bound, the rate limit says when it recovers, upstream-busy refunds, the inventory and the RFC 9728 document match the code, the relay door forwards exactly one provider and nothing else, and both doors answer the same toolset. The domain servers carry their own suites in their own repositories; they run here too if you call cargo test on their manifests.

9. When something does not work

You see	What it means	What to do
error: package … requires rustc 1.xx	your Rust is too old	rustup update stable
the gateway exits at once naming registry/entries	--root does not point at this repository's root	pass --root . from the clone
403 on /mcp behind a proxy	the Host header is not on the allow-list	add --mcp-host <public name>
429 with Retry-After	the rate limit, by design	wait as long as the header says
upstream-busy in live mode	the polite brake declined to send	retry; the charge was refunded

Where this repository comes from

The association develops all its modules in one corpus, on its own GitLab, where every change runs through a gate (formatting, Clippy without warnings, all tests, seal and drift checks). This repository is assembled from that corpus by the publication lane, tested in the assembled tree, and pushed here.

This copy was published from corpus commit 835819c on 2026-09-07.

Contributing, security, licence

• Issues here are welcome: a wrong result, a missing case, an unclear sentence in this README. Please include the command you ran and what came back.
• Changes go through the corpus and arrive here with the next publication; a pull request here is read and carried over by hand.
• Security reports, in confidence: [email protected]. The association answers within a working week.
• Licence: Apache-2.0 for the gateway and the domain servers (LICENSE, attribution in NOTICE); the auth profile under profile/ declares MIT; the vendored upstream code and the recorded federal answers keep their own terms. REUSE.toml names the licence of every path.