← MCP Registry

GitHub · README

MCP Registry

Private repositoryThe source is private, so its README is published here. This is the project’s documentation, not its code.

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.

Connect an agent

On any machine on the tailnet:

curl -fsSL http://ubuntu03:30105/install.sh | sh

It 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

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:

Each served server is also available on its own, unprefixed, at /mcp/<name>.

Add a server

  1. Add an entry to registry.json:
    {"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"}
    For hosted, give hosted.bundle (the script, relative to this repo, usually in a sibling checkout), hosted.command, hosted.args (/servers/<file>) and hosted.env. The pod is python:3.13-alpine, so a hosted server must be Python standard library only.
  2. 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

Gotchas

← Back to projectAll projects