← All projects MCP Registry Registry ↗

Tailnet MCP registry · Kubernetes

One endpoint.
Every agent.

Every coding agent on my tailnet connects to one URL. Instead of loading every server's tools at once, the gateway hands the agent an index of servers and loads only the ones it picks — and they expire when the work moves on — so a session starts lean and the rest is one call away. A server added to the registry reaches every connected agent within a minute, with no config change on any machine.

The registry link works on devices connected to my tailnet.

Claude CodeCodexOpenCodeHermesAny new machineinstall.sh
MCP Registry gateway http://ubuntu03:30105/mcp k8s namespace mcp-registry · re-reads registry.json every 5 s
Hostedrun inside the pod Remoteproxied over the tailnet Machine-locallisted with a connect line
Core servers are loaded whole; the rest are indexed and pulled in on demand. Every served tool is <server>__<tool>.
20servers indexed
11served by the gateway
14tools loaded at the start
0credentials held by the gateway

The agent's rolodex

A gateway that advertises every server's tools puts all of them in the model's context on every turn — 121 tools, and the schemas, not the connections, are what crowd a session out. So the gateway ships as an index first: find a server, load it, then call it.

ubuntu03:30105
The registry page in compact mode: the gateway endpoint, the find/load/call lines, and the counts — 20 servers indexed, 14 tools loaded at the start, 109 more on demand
The registry page, in compact mode. The endpoint, the three calls an agent makes, and the counts: what is loaded now against what is one search away.

Find index

registry__search_servers matches what the agent wants to do against every server's name and description, and its tool names on request. It returns a shortlist of names — cheap, no schemas.

Load on demand

registry__mcp_use pulls one server's tools into the session as <server>__<tool> and tells the client the tool list changed. Nothing else in the registry costs a token.

Call same gateway

Calls route through the same URL. A server stays loaded while it is used — half an hour idle and it drops out again — and machine-local servers are never proxied: the answer carries the line to connect one on its own machine.

The same index is on the HTTP surface for anything that is not an MCP client: /servers/search?q=, /servers/use?server= and /tools/<server>/<tool>, with the server names and tools in the registry API. The rule that makes it work: the index carries names and descriptions; schemas are fetched only for the servers the agent picks.

Why new agents get it straight away

The whole point is that nothing has to be set up twice: not for a new session, not for a new server, and nearly not for a new machine.

New sessions inherit it

The gateway is a user-level server in Claude Code, Codex, OpenCode and Hermes, so every new session and every subagent on a connected machine starts with it.

New servers need no client change

The gateway re-reads registry.json every five seconds and tells connected agents. A new server is searchable at once and loads on demand; agents that ignore the notification find it at their next session.

New machines take one line

curl -fsSL http://ubuntu03:30105/install.sh | sh finds the coding agents installed there and adds the same server to each. Re-running it is safe, and every config file it edits is backed up first.

Agents can find it on their own

~/AGENTS.md names the registry, /.well-known/mcp.json describes it, and registry__list_servers lists everything, including servers that only run on one machine.

Connect an agent

One server called registry, at user level. Click a line to copy it.

Any machineevery agent foundcurl -fsSL http://ubuntu03:30105/install.sh | sh
Claude Codeclaude mcp add --transport http -s user registry http://ubuntu03:30105/mcp
Codexcodex mcp add registry --url http://ubuntu03:30105/mcp
OpenCode"mcp": { "registry": { "type": "remote", "url": "http://ubuntu03:30105/mcp" } }
Hermesmcp_servers: registry: url: http://ubuntu03:30105/mcp
Anything elseStreamable HTTPhttp://ubuntu03:30105/mcp

The registry itself is served in the MCP Registry v0 shape at /v0/servers, so registry-aware tools can read it too.

Inside the registry

The live page, captured from the cluster. Three kinds of entry, one list.

ubuntu03:30105
The registry page: the gateway URL, connect lines for each agent and the Project Context server with its four tools
The registry page. The endpoint, a copyable line for each agent, and each server's status, tools and source.

Hosted served

A stdio server the gateway runs in its own pod. Project Context is one: every project brief, read from this site, available to agents on any machine.

Remote served

A Streamable HTTP server anywhere on the tailnet, proxied through the gateway. Servers that need the agent's own token, like Cloudflare's, are listed but not proxied.

Machine-local listed

Servers that need one machine's screen or files, like Peekaboo and Screen Pointer on my Mac. The registry gives the exact line to connect them there.

Add a server

One entry, one deploy. Every connected agent picks it up without being touched.

1 · Describe it in registry.json

{
  "name": "my-tool",
  "title": "My Tool",
  "description": "What an agent can do with it.",
  "kind": "remote",
  "url": "http://ubuntu03:30110/mcp"
}

2 · Publish

./deploy/deploy.sh updates the registry ConfigMap in place, without a restart, and tells the kubelet to sync it at once. Within about a minute the server is searchable in every connected agent, and its tools load as my-tool__… when an agent asks for them.

A change to the gateway code or to a hosted server's script rolls the pod instead. A server that stops answering turns red on the page and is retried every 30 seconds.

Private by design

It lives on my tailnet.

The registry runs on my home Kubernetes cluster and is not published to the internet. It holds no credentials: servers that need a token are listed, and each agent brings its own.

Requests must name one of my hosts, and browser origins are checked against the same list, so a web page cannot reach it through DNS rebinding.