# MCP Registry

One MCP endpoint for every agent on my tailnet. Claude Code, Codex, OpenCode and Hermes connect to a single URL and get every shared MCP server through it; a server added to the registry reaches all of them within a minute, and a new machine joins with one command. It runs as a small gateway on my Kubernetes cluster and also lists the servers that only run on one machine.

**Status:** Live · Agents · 2026

- **Local checkout:** `/Users/simon/Developer/mcp-registry` (branch `main`, last commit cc6e3d1, 2026-11-07 — Loaded servers expire when they go idle)
- **Uncommitted changes:** 2 file(s) at brief generation time
- **Repository:** https://github.com/ShimonNavon/mcp-registry
- **On another machine:** `git clone https://github.com/ShimonNavon/mcp-registry` — the paths below are Simon's Mac
- **Live:** http://ubuntu03:30105/
- **How it works:** https://projects.navonsimon.com/mcp-registry.html
- **GitHub:** https://projects.navonsimon.com/repo/mcp-registry
- **Where it runs:** namespace mcp-registry · NodePort 30105 · tailnet only
- **Note:** Registry on my tailnet

## Stack

Python stdlib, MCP Streamable HTTP, Kubernetes, Tailscale

## Start here

- `registry.json` — the registry: every MCP server, its kind (hosted / remote / local) and how to run it
- `gateway.py` — the whole service: registry API (/v0/servers), MCP gateway (/mcp), SSE list_changed, page, installer
- `install.sh` — served at /install.sh; adds the gateway to Claude Code, Codex, OpenCode, Hermes, Gemini CLI, Cursor
- `page.html` — the registry page at http://ubuntu03:30105/
- `deploy/deploy.sh, deploy/k8s.yaml` — namespace mcp-registry, NodePort 30105, ConfigMaps gateway-code, hosted-servers, registry
- `tests/test_gateway.py` — end-to-end tests against a real gateway process

## Commands

- **Run locally:** `REGISTRY_FILE=registry.json PUBLIC_URL=http://localhost:8080 python3 gateway.py`
- **Focused tests:** `python3 -m unittest discover -s tests`
- **Publish:** `./deploy/deploy.sh`
- **Connect a machine:** `curl -fsSL http://ubuntu03:30105/install.sh | sh`

## Deploy and where it runs

- Namespace mcp-registry, Deployment gateway (python:3.13-alpine + ConfigMaps), NodePort 30105; reach it at http://ubuntu03:30105/.
- registry.json changes are picked up live (no restart); gateway code or a bundled hosted script changes roll the pod via a hash annotation.
- Hosted servers are bundled from sibling checkouts (hosted.bundle), e.g. ../my-projects/tools/context_mcp.py, and run with CONTEXT_URL pointing at the in-cluster site.

## Current state

Live since 2026-10-27. Runs in compact mode (the rolodex): a session starts with 14 tools (4 collection tools + the LEAN_CORE servers project-context and agent-link) instead of 121, finds the rest with registry__search_servers and loads one with registry__mcp_use. 20 servers indexed, 11 served by the gateway. Claude Code, Codex, OpenCode and Hermes on the Mac are connected as server 'registry'.

## Watch out

- Compact mode is the default: LEAN=1 with LEAN_CORE=project-context,agent-link in deploy/k8s.yaml. LEAN=0 serves every server's tools up front (121 tools).
- Non-core servers are not in the tool list until registry__mcp_use loads them; calling one by name anyway works and loads it for the session.
- Gateway tool names are <server>__<tool>; in Claude Code that is mcp__registry__project-context__get_brief.
- The index is also on HTTP: /servers/search?q=, /servers/use?server=, /servers/<name>?tools=1, /tools/<server>/<tool>.
- Only put read-safe tools behind hosted/remote: every agent on the tailnet can call them. The gateway holds no credentials.
- Hosted servers must be Python stdlib only (the pod has no pip installs) and must not fetch navonsimon.com with Python's default User-Agent (Cloudflare blocks it).
- The Mac keeps its local project-context stdio server too: local reads the working tree, the gateway reads the published site.

## Secrets — locations only, never print values

- None. The gateway holds no credentials by design.

## Tags

MCP, Gateway, Tailscale, Kubernetes

---

Brief generated 2026-11-08 from `~/Developer/my-projects/context/`. Canonical URL: https://projects.navonsimon.com/context/mcp-registry.md
