Register MCP

🇨🇭 Part of the [Swiss Public Data MCP Portfolio](https://github.com/malkreide)

register-mcp

MCP Server for the Swiss Federal Commercial Register (Zefix/Handelsregister), with a company-UID join to the official gazettes (SHAB + cantonal Amtsblätter)

🇩🇪 Deutsche Version

---

Overview

register-mcp provides AI-native access to two Swiss federal data sources, joined on the UID, all without authentication:

The two sources share one key — the UID. The value is in the join: Zefix tells you whether a company exists; the gazette tells you what has been published about it.

The gazette access here is deliberately company-scoped only — keyed on a company UID or a specific publication id. There is no free-text / person-name gazette search in this server; that would be a profiling tool over the gazette's person-data rubrics (bankruptcy, debt-collection, inheritance). Broad Amtsblatt platform search (procurement, cantonal notices, full-text) is proposed as a separate amtsblatt-mcp — see docs/amtsblatt-mcp-proposal.md and the Data Protection & Scope section below.

Designed for Swiss public administration use cases: vendor verification, contract partner due diligence, and supplier onboarding — all via natural language queries.

Anchor demo query: *"Before we sign a framework agreement with Lehrmittelverlag Zürich AG: is the company active in the commercial register, what is its UID and stated purpose — and, via that UID, what has the official gazette published about it (HR mutations, calls to creditors, any bankruptcy)?"*

That single question walks the whole tool chain across both sources:

zefix_search_company  →  zefix_verify_company  →  gazette_company_publications(uid=…)  →  gazette_get_publication(id=…)

---

Features

• 🏛️ 9 tools across two sources — company search & verification (Zefix) + the company-scoped gazette join (SHAB/cantonal)
• 🔗 `gazette_company_publications` — the UID join: everything published about a company
• 🛡️ Data-protection-safe by construction — the only gazette entry points are UID- or id-scoped; no person-name search entry exists (see *Data Protection & Scope*)
• 🔍 `zefix_verify_company` — quick active/dissolved status check
• 🌐 Bilingual output (Markdown / JSON) with per-source attribution + provenance
• 🔓 No API key required — open data from zefix.admin.ch and amtsblattportal.ch
• ☁️ Transports — stdio (Claude Desktop) + Streamable HTTP at /mcp (cloud, native MCP spec 2026-07-28); SSE kept for existing deployments

---

Prerequisites

• Python 3.11+
• uv (recommended) or pip

---

Installation

# Clone the repository

git clone https://github.com/malkreide/register-mcp.git cd register-mcp

Install

pip install -e .

or with uv:

uv pip install -e .

Or with uvx (no permanent installation):

uvx register-mcp

---

Quickstart

# stdio (for Claude Desktop)

python -m register_mcp.server

Streamable HTTP (cloud deployment, endpoint /mcp) — MCP_API_KEY is REQUIRED

MCP_API_KEY=$(openssl rand -hex 32) MCP_TRANSPORT=streamable-http PORT=8000 \ python -m register_mcp.server

HTTP / Cloud Deployment

Two HTTP transports are available:

streamable-http runs stateless with JSON responses: no Mcp-Session-Id, no session held in a single process, so a second instance needs no sticky sessions.

⚠️ Upgrade note (0.7.0): the container image and compose.yaml now

default to streamable-http. Clients configured with …/sse must switch to

…/mcp, or the deployment sets MCP_TRANSPORT=sse explicitly.

With either HTTP transport, the server enforces:

• Bearer-token auth — set MCP_API_KEY to a secret string. Clients must send Authorization: Bearer on every request. Missing or wrong → HTTP 401. The server refuses to start without MCP_API_KEY set.
• Rate limiting — sliding window per bearer-token hash. Defaults: 60 req / 60 s. Tunable via MCP_RATE_LIMIT and MCP_RATE_WINDOW. Exceeding the limit returns HTTP 429 with Retry-After.
• Structured JSON logging — every tool call emits one line to stderr with tool, status, latency_ms. Auth failures and rate-limit events are logged at WARNING level. Configure verbosity with LOG_LEVEL (default INFO).
• Reference-data cache — Zefix legal-forms are cached for 24h (LEGAL_FORMS_TTL seconds) to avoid an extra upstream call per tool invocation.
• Egress allow-list — outbound HTTP is restricted to www.zefix.admin.ch and amtsblattportal.ch via an httpx request hook that also fires on redirects. A Location header pointing elsewhere raises EgressDenied and is never followed. Override with MCP_ALLOWED_HOSTS=host1,host2 (comma-separated, lower-case).

⚠️ Upgrade note (0.2.x → 0.3.0): amtsblattportal.ch was added to the

default allow-list when the gazette tools shipped. If your deployment

pins MCP_ALLOWED_HOSTS, that value overrides the default entirely —

add amtsblattportal.ch to it, or every gazette_* call will raise

EgressDenied.

• Optional OpenTelemetry tracing — install with pip install register-mcp[otel] and set OTEL_EXPORTER_OTLP_ENDPOINT (e.g. http://otel-collector:4318/v1/traces). Without the extra or without the env var the server stays silent — no hard dependency on the OTel SDK.

For multi-instance deployments, place a real gateway (Cloudflare, Railway internal networking, an API-Gateway with Redis-backed rate limiting) in front of the in-memory limiter, which is per-process by design.

Container deployment

A minimal multi-stage Dockerfile ships with the repo. The image runs as a non-root mcp user; dependencies are resolved from uv.lock (uv sync --frozen), so the build is reproducible.

docker build -t register-mcp:local .

docker run --rm -p 8000:8000 \ -e MCP_API_KEY="$(openssl rand -hex 32)" \ register-mcp:local

→ Streamable HTTP on http://localhost:8000/mcp

For local iteration there is a compose.yaml with read_only, cap_drop: ALL and no-new-privileges:

MCP_API_KEY=$(openssl rand -hex 32) docker compose up --build

See SECURITY.md for hardening notes (egress restriction, key rotation, SIEM forwarding).

Try it immediately in Claude Desktop:

*"Is Lehrmittelverlag Zürich AG active in the commercial register?"*

*"Look up the company with UID CHE-108.954.978"*

*"List all Swiss legal forms"*

---

Configuration

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{

"mcpServers": { "register": { "command": "python", "args": ["-m", "register_mcp.server"] } } }

Or with uvx:

{

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

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Cloud Deployment (Streamable HTTP for browser access)

For use via claude.ai in the browser (e.g. on managed workstations without local software):

Render.com (recommended):

1. Push/fork the repository to GitHub
2. On render.com: New Web Service → connect GitHub repo
3. Set start command python -m register_mcp.server and the environment variables MCP_TRANSPORT=streamable-http and MCP_API_KEY= (Render provides PORT)
4. In claude.ai under Settings → MCP Servers, add: https://your-app.onrender.com/mcp

💡 *"stdio for the developer laptop, Streamable HTTP for the browser."*

---

Available Tools

Zefix — commercial register (6):

Amtsblattportal — the company-scoped gazette join (3):

The prefix is gazette_, not shab_, because the source covers SHAB and the cantonal gazettes. Every entry point is UID- or id-scoped — see Data Protection & Scope. Broad, non-company gazette search (procurement, cantonal full-text) is scoped to the separate amtsblatt-mcp.

Example Use Cases

---

Architecture

                                                          ┌──────────────────────────────┐

┌────▶│ Zefix (Handelsregister) │ │ │ www.zefix.admin.ch │ ┌─────────────────┐ ┌──────────────────────────┴─┐ │ ZefixREST/api/v1 │ │ Claude / AI │────▶│ register-mcp │ └──────────────────────────────┘ │ (MCP Host) │◀────│ (MCP Server) │ ┌──────────────────────────────┐ └─────────────────┘ │ 9 Tools (zefix_ + gazette_) ├──▶│ Amtsblattportal │ │ stdio | HTTP /mcp | SSE │ │ amtsblattportal.ch/api/v1 │ │ Egress allow-list │ │ SHAB + cantonal gazettes │ │ No authentication required │ └──────────────────────────────┘ └──────────────────────────────┘ join key: UID (CHE-XXX.XXX.XXX)