An MCP registry of record is the one list of approved MCP servers that your gateway config, client allowlists and shadow scans are all generated from and checked against. Run it as a private registry that implements the official MCP Registry API, add your own fields for owner, business domain, exact URL or command, and what each server may reach, and make agentgateway’s targets and policies an output of the record instead of a second list.
I work at Solo.io, which makes agentgateway and created agentregistry.
This page is the record: the fields it needs, the configs you generate from it, and the diffs that catch drift. Why shadow MCP servers are hard to track is the hub. Run a private MCP registry is how you stand one up. Nothing below is a harness result, and no search numbers appear here.
What makes a registry “of record” and not just a catalog?
A catalog says what exists. A record says what is approved, who owns it, and what it may reach, and other systems are built from it. The test is simple: if you delete an entry, does the gateway stop routing to that server? If not, it is a catalog.
If the gateway config, the client allowlists and the scan baseline are three separate lists, they drift, and drift is where shadow servers live. The point of generating the gateway from the record is that there is only one place to approve or revoke a server. Edit the record, apply the output, and the target list and the allow rules move together. A hand-edited gateway config that is kept in sync with a spreadsheet is two lists again.
Can the official MCP Registry be your registry of record?
No, for three reasons documented on the MCP Registry about page. The official registry is in preview and lists only publicly accessible servers; it does not support private ones. Its maintainers say the official codebase is not designed for self-hosting, and they cannot support that use case. Host applications are not meant to consume it directly; they should consume registries that implement its OpenAPI spec.
That spec is the useful part. A private registry that speaks the same API works with existing clients. Run a private MCP registry is the setup.
What does server.json already give you?
The official format gives you the “what”: a name in reverse-DNS form, where to get the server (a package or a remote URL), how to run it, a version, and a description. The about page calls that metadata “deliberately unopinionated.” Downstream aggregators are expected to add curation. The first field a registry of record needs, who owns the server, is exactly the one the public registry chose to leave out. There is no owner, no approval, and no reach.
What fields does an MCP server record need?
Each field exists because an output uses it.
| Field | Why it exists | Who uses it |
|---|---|---|
| Owner (a team, not a person) | Someone has to approve changes and answer when the server drifts | Reconcile, review |
| Business domain | Group servers the way the company is organized, not by whoever stood the process up | Federation grouping; see register servers by business domain |
| Transport and exact remote URL, or exact stdio command and arguments | This is what allowlists and gateway targets match on, so it has to be exact | Client allowlists, gateway targets |
| Version pin | A moving tag is not a record | Client config, scan diff |
| Tool definition digest | A package version does not pin what the server says about its tools at runtime | Drift alert; see pin tool definitions |
| Systems it may reach (hostnames or CIDRs) | The egress allow list should come from the record, not a fourth file | Egress allow rules |
| Workload identity or token audience | “Is this our server” should be a verified credential, not a name | Gateway authentication; see SPIFFE for AI agents |
| Status: approved, deprecated, revoked | Every generated output has to know whether the server is still allowed | Every output |
| Review-by date | Stale approvals are how revoked servers linger | The stale diff |
Where those extra fields live: server.json’s _meta field takes custom metadata under a reverse-DNS key, as documented in the server.json format spec. The official registry requires the key io.modelcontextprotocol.registry/publisher-provided for publishers. A private registry can use its own key, such as com.example.record. I have not confirmed that agentregistry v0.4.0 keeps custom _meta through its v0.1 compatibility API, so keep the extra fields in the same declarative record you apply, even if you also store a copy under _meta.
How do you generate agentgateway config from the record?
Start with standalone, then Kubernetes. I have not run a generator harness for this page, so what follows is the shape of the output, not a tool.
In standalone mode, each approved record becomes an MCP target: a name plus the exact URL or the exact stdio command from the record. One mcpAuthorization policy allows only those targets, matching on mcp.tool.target, as documented in the standalone MCP authorization docs. The authorization rules below are copied from that doc, with the idea that each mcp.tool.target value is a name from the record:
mcp:
port: 3000
policies:
mcpAuthorization:
rules:
# Allow anyone to access tools on the public-tools target
- 'mcp.tool.target == "public-tools"'
# Only authenticated admins can access tools on the admin-tools target
- 'mcp.tool.target == "admin-tools" && has(jwt.sub) && "admin" in jwt.roles'
targets:
- name: public-tools
stdio:
cmd: npx
args: ["@modelcontextprotocol/server-everything"]
- name: admin-tools
stdio:
cmd: npx
args: ["@mycompany/admin-server"]
Push the result with agctl standalone apply, which the v1.7.0 release notes say manages a standalone agentgateway through its admin API with get and apply, including policies and MCP targets.
On Kubernetes, each approved record becomes a static target on an AgentgatewayBackend, plus an AgentgatewayPolicy with CEL tool rules. Tool access is allowed by default until that policy attaches. Prefer static targets for record-backed servers over label selectors. A selector admits any Service that carries the label and appProtocol: agentgateway.dev/mcp, and a label selector can let a server in.
Egress comes from the record’s “may reach” field: that list becomes the allow list in a Kubernetes NetworkPolicy or in the CONNECT egress proxy (v1.6.0, tested on that page).
Egress rules only work when the MCP server’s traffic is forced through the gateway.
Revocation is a status flip, then a regenerate. The target disappears on the next apply. The v1.7.0 notes fixed resumed sessions keeping outdated settings after a configuration change, so if you are on an earlier version, test revocation with a new session. That session caveat is part of why a gateway may not be blocking shadow servers.
How do you generate client allowlists from the record?
Claude Code’s managed MCP settings key allowedMcpServers entries on serverUrl for remote servers and serverCommand for stdio. To make the list authoritative, set allowManagedMcpServersOnly to true in a managed settings source, together with that allowlist. serverName is a user-assigned label and should not be the key. That is a client fact, not a ranking.
How do you reconcile the record against what is running?
Three diffs, each with a source and a next step. Pick your own stale window; this page does not suggest a number.
- Scan results minus the record: those are shadow servers, running somewhere you can see and not in the approved list. Find shadow MCP servers in your environment is the walk, and how to fingerprint an MCP server is how you identify what you found.
- Gateway metrics minus the record: servers configured on the gateway that nobody registered. In standalone agentgateway, that signal is the
serverlabel onmcp_requests_total, as documented in the standalone MCP observability docs. That is config drift, a server the gateway already routes to that the record never approved. - Record minus anything seen in your chosen window: stale entries to review or revoke.
Who is allowed to change the record?
Treat it like code. Keep entries as declarative files in a repo, and require a pull request with owner approval. agentregistry v0.4.0 manages servers as declarative resources with arctl apply, which is how the live private MCP registry write-up publishes them. That flow fits a record of record. This is not a comparison of tools.
What a registry of record does not do
It blocks nothing by itself. Vendor-hosted connectors never cross your network. A laptop with open egress can still reach a server that is not in the record. The record is only as strong as the gateway and the egress it generates, which is the work on how to stop shadow MCP servers.
Egress and gateway controls only work when the MCP server’s traffic is forced through the gateway.