One MCP endpoint for every agent on Simon's tailnet: http://ubuntu03:30105/mcp.
An agent connects to the gateway once and gets every shared MCP server's tools, named
<server>__<tool>. Adding a server to registry.json and running ./deploy/deploy.sh reaches every
connected agent within about a minute, with no config change on any machine. The registry also lists
servers that only run on one machine (the Mac's Peekaboo, Screen Pointer, Build Ledger), with the
exact line to connect each one directly.
- Registry page: http://ubuntu03:30105/ (tailnet only)
- How it works (public): https://projects.navonsimon.com/mcp-registry.html
- Registry API: http://ubuntu03:30105/v0/servers (the MCP Registry v0 shape)
Connect an agent
On any machine on the tailnet:
curl -fsSL http://ubuntu03:30105/install.sh | shIt finds the coding agents installed there and adds one user-level server named registry to each.
Re-running it is safe. Claude Code and Codex are set up through their own CLIs. OpenCode, Hermes,
Gemini CLI and Cursor configs are edited in place, after a .bak.<epoch> copy is saved.
By hand:
| Agent | Config |
|---|---|
| Claude Code | claude mcp add --transport http -s user registry http://ubuntu03:30105/mcp |
| Codex | codex mcp add registry --url http://ubuntu03:30105/mcp |
| OpenCode | "mcp": { "registry": { "type": "remote", "url": "http://ubuntu03:30105/mcp" } } |
| Hermes | mcp_servers: → registry: → url: http://ubuntu03:30105/mcp |
| Anything else | Streamable HTTP at http://ubuntu03:30105/mcp; discovery at /.well-known/mcp.json |
Why new agents get it immediately
- New sessions read the user-level config, so every new Claude Code, Codex, OpenCode or Hermes session (subagents included) on a connected machine starts with the registry.
- New servers need no client change. The gateway re-reads
registry.jsonevery 5 seconds and sendsnotifications/tools/list_changedto connected agents over theGET /mcpstream. A client that ignores the notification still picks the server up on its nexttools/list, which is at latest the next session. - New machines need one command (
install.shabove). - Agents that don't know about it can find it:
~/AGENTS.mdnames the registry and/.well-known/mcp.jsondescribes it.
As of 2026-10-27, Claude Code, Codex, OpenCode and Hermes on Simon's Mac are connected. The Ubuntu servers run no coding agents.
Servers
registry.json is the registry. Each entry has a kind:
| Kind | What the gateway does | Example |
|---|---|---|
hosted |
Runs the stdio server inside its own pod and serves it | project-context (briefs read from the published site) |
remote |
Proxies a Streamable HTTP server running anywhere on the tailnet; "proxy": false lists it only, for servers that need the agent's own credentials |
cloudflare-api (listed only) |
local |
Lists a stdio server that only runs on one machine, with the line to connect it directly. Never proxied | peekaboo, screen-pointer, build-ledger on the Mac |
Built-in tools on the gateway:
registry__list_servers: every entry, its status and tools.registry__get_server: one entry, with the exact connect line for Claude Code, Codex, OpenCode and Hermes.
Each served server is also available on its own, unprefixed, at /mcp/<name>.
Add a server
- Add an entry to
registry.json:For{"name": "my-tool", "title": "My Tool", "description": "What an agent can do with it.", "kind": "remote", "url": "http://ubuntu03:30110/mcp", "repository": "https://github.com/ShimonNavon/my-tool"}hosted, givehosted.bundle(the script, relative to this repo, usually in a sibling checkout),hosted.command,hosted.args(/servers/<file>) andhosted.env. The pod ispython:3.13-alpine, so a hosted server must be Python standard library only. - Run
./deploy/deploy.sh.
If only registry.json changed, the pod is not restarted: the ConfigMap is updated in place and
nudged so the kubelet syncs it straight away. Changes to the gateway code or to a bundled script
change a hash on the pod template, and the pod rolls.
Files
| File | What |
|---|---|
gateway.py |
The whole service: registry API, MCP gateway, SSE notifications, page and installer routes. Standard library only |
registry.json |
The registry |
page.html |
The registry page at / |
install.sh |
The installer served at /install.sh (__URL__ is filled in by the gateway) |
deploy/k8s.yaml, deploy/deploy.sh |
Namespace mcp-registry, NodePort 30105, ConfigMaps gateway-code, hosted-servers, registry |
tests/ |
End-to-end tests against a real gateway process |
HTTP routes
| Route | |
|---|---|
POST /mcp |
The gateway (Streamable HTTP, stateless, JSON replies) |
GET /mcp |
text/event-stream of tools/list_changed notifications |
POST /mcp/<name> |
One served server alone |
GET /v0/servers, /v0/servers/<name> |
Registry API; ?search=, ?limit=, ?cursor=. Names are com.navonsimon/<name>; per-entry status, tools and connect lines are under _meta["com.navonsimon/registry"] |
GET /install.sh |
The installer |
GET /.well-known/mcp.json |
Discovery |
GET /healthz |
Liveness |
Run and test locally
REGISTRY_FILE=registry.json PUBLIC_URL=http://localhost:8080 python3 gateway.py python3 -m unittest discover -s tests
Hosted entries point at /servers/... paths that exist only in the pod, so locally they show as not
answering. The tests use their own registry with a stdio echo server and a remote that loops back
through the gateway.
Security
- The registry is reachable on the tailnet and the home LAN, like every NodePort on the cluster. It is not published through Cloudflare.
- The gateway holds no credentials. Servers that need a token (
cloudflare-api) are listed, not proxied, so each agent brings its own. - Requests must name an allowed host (
ubuntu03,ubuntu04,*.ts.net, an IP or localhost), and browserOrigins are checked against the same list. This blocks DNS-rebinding attacks from web pages. - Only expose read-safe tools through
hosted/remote: every agent on the tailnet can call them.
Gotchas
- Tool names are
<server>__<tool>inside the gateway, so in Claude Code they appear asmcp__registry__project-context__get_brief. - On the Mac, the local
project-contextstdio server reads the working tree, while the gateway's copy reads what is published on projects.navonsimon.com. Both are kept. - A served server that stops answering shows red on the page and is retried every 30 seconds.
- A Cloudflare rule blocks Python's default
urllibuser agent on navonsimon.com sites. Hosted servers should send their ownUser-Agentor use in-cluster URLs.