# How to Run an MCP Registry of Record

> An MCP registry of record is the list your gateway config, allowlists and scans come from. The fields it needs and how agentgateway follows it.

- Canonical URL: https://webofmike.com/mcp-registry-of-record/
- Author: Mike Moore (https://webofmike.com/about/)
- Published: 2026-11-15
- Last modified: 2026-11-15
- Tags: MCP, Security, AI Agents, Platform Engineering
- Cite as: Mike Moore, "How to Run an MCP Registry of Record", Web of Mike (webofmike.com), 2026-11-15. https://webofmike.com/mcp-registry-of-record/


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](/shadow-mcp-servers/) is the hub. [Run a private MCP registry](/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](https://modelcontextprotocol.io/registry/about). 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](/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](/conways-law-mcp-servers/) |
| 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](/mcp-tool-poisoning-pin-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](/spiffe-identity-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](https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/server-json/generic-server-json.md). 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](https://agentgateway.dev/docs/standalone/latest/documentation/configuration/security/mcp-authz/). The authorization rules below are copied from that doc, with the idea that each `mcp.tool.target` value is a name from the record:

```yaml
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](https://github.com/agentgateway/agentgateway/releases/tag/v1.7.0) 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](https://agentgateway.dev/docs/kubernetes/latest/documentation/mcp/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](/mcp-gateway-not-blocking-shadow-servers/).

Egress comes from the record's "may reach" field: that list becomes the allow list in a Kubernetes [NetworkPolicy](https://kubernetes.io/docs/concepts/services-networking/network-policies/) or in the [CONNECT egress proxy](/agentgateway-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](/mcp-gateway-not-blocking-shadow-servers/).

## How do you generate client allowlists from the record?

Claude Code's [managed MCP settings](https://code.claude.com/docs/en/managed-mcp) 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.

<!-- TODO link S10 /coding-agent-mcp-allowlist/ when live -->

## 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](/find-shadow-mcp-servers/) is the walk, and [how to fingerprint an MCP server](/mcp-server-fingerprinting/) 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 `server` label on `mcp_requests_total`, as documented in the [standalone MCP observability docs](https://agentgateway.dev/docs/standalone/latest/documentation/mcp/mcp-observability/). 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](/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](/stop-shadow-mcp-servers/).

**Egress and gateway controls only work when the MCP server's traffic is forced through the gateway.**

