Skip to the content

Allow only vetted MCP servers

Mirror the MCP registry, have Central Lite sign it for your machines, and let agents launch only servers resolved from that signed snapshot.

Built, not yet claimed preview: this guide describes a package that has not passed its release gate.

Mirror the MCP registry on a machine that can reach it, read what you mirrored, have Central Lite sign it and send it to your enrolled machines, then let agents launch only servers resolved from that signed snapshot, with the package, its exact version and its integrity all taken from it.

1. Mirror the registry on a machine that can reach it

Your machines never call the MCP registry, and neither does Central Lite: an administrator mirrors it with agentgarm mcp registry seed, by default from the official registry (--registry names another, https:// only). Each server document is checked against its own pinned server.json schema; the rest are refused and counted (retired or unknown schema, invalid, duplicate). For each npm and PyPI package version it then asks the official package registry for the integrity lockdown will check: npm's sha512- dist.integrity, or the sha256 of the release's single pure-Python wheel. A package it cannot pin is unpinnable, a package of another ecosystem is unsupported_ecosystem, and a failed answer stays unresolved until the next seed retries it; none of them can be launched.

It writes payload.json, header.bin and signing-input.bin into a new or empty directory, never replacing a file, and prints the counts.

agentgarm mcp registry seed --out seed --sequence 1

2. Sign a copy and read what you mirrored

search and show read only a snapshot that verifies, so to read the mirror before it goes anywhere, sign signing-input.bin with an Ed25519 key of your own. AgentGarm's binaries never sign: use any signer, giving 64 raw bytes or 128 hex digits. assemble checks the signature against --key (the key's id and its public half in hex) before it writes the snapshot, and verify checks the signature, the validity window and the minimum version before it reads the payload, refusing an expired snapshot.

show prints each version's status, its namespace kind and who could have published it (for an io.github.<org> namespace, an org admin or any GitHub Actions workflow in a repository the org owns), the publisher's text escaped with the tool-description checks' findings, and each package's integrity pin state. A publisher's own fileSha256 is shown as theirs and is never used as integrity.

agentgarm mcp registry assemble --header seed/header.bin --payload seed/payload.json --signature seed/signature.bin --key review=ed25519:$REVIEW_KEY --out seed/review.snapshot
agentgarm mcp registry verify --snapshot seed/review.snapshot --key review=ed25519:$REVIEW_KEY
agentgarm mcp registry search weather --snapshot seed/review.snapshot --key review=ed25519:$REVIEW_KEY
agentgarm mcp registry show io.github.example-org/weather --snapshot seed/review.snapshot --key review=ed25519:$REVIEW_KEY

3. Import it into Central Lite

garm-central registry import takes the seed's payload, checks it as a reader does, and replaces the mirrored versions; --header keeps its mirror time. Central Lite then signs the next snapshot with the org's policy role key, checks it as a machine will open it, and sends it over the control channel to every enrolled machine. A snapshot is valid for 30 days, and garm-central serve signs a fresh one when less than half of that is left; garm-central registry publish signs one at once. Central Lite also answers the registry's read API (/v0.1/servers) on its port from the newest signed snapshot, only to enrolled machines unless serve runs with --registry-api anonymous.

Your org's own servers go in with registry server add, from their server.json and the integrity you state for their packages (--pins); a package without one stays unresolved and never launches. garm-central registry list shows every version with its origin (mirror or private), its status and each package's pin state, and garm-central registry show the newest snapshot.

garm-central registry import seed/payload.json --header seed/header.bin
garm-central registry list
garm-central registry server add --server server.json --pins pins.json

4. Check what a machine installed

Only a root install enrolled in Central Lite receives the snapshot: a no-root install is never enrolled, so it has none, and every registry name its policy names is refused. The root agentgarmd checks the snapshot's signature and that it is newer than the last, without parsing its contents, and installs it readable by every local account, so anyone on the machine can read your org's private server list. agentgarm mcp registry installed refuses a directory anyone but root can write, verifies the snapshot again, and prints its source, sequence, version count, upstream and the time it is valid until.

agentgarm mcp registry installed

5. Pin a version, or name it in policy

agentgarm mcp registry pin turns one version of the installed snapshot into policy, in two forms. The first is the exact mcp.packages and mcp.servers entries package lockdown launches: the package, its exact version and its integrity, copied into your policy, where they no longer follow the registry. It is printed under a top-level mcp:, so nest it under security_boundaries: when you copy it into a policy. The second, printed as a comment, is an mcp.allow entry naming the server by its registry name, which agentgarm-session resolves against the installed snapshot at every launch, so a version deleted later is refused there.

pin refuses (exit 2) a deleted version, a package whose integrity is unresolved, unpinnable or of an ecosystem lockdown does not launch, and anything but a stdio npm or PyPI package, and warns on a deprecated one. In the mcp.allow form, set version and namespace_kinds: without a version each launch takes the version the snapshot marks latest, if it is not deleted, which the lint reports as registry_latest, because anyone who can publish in the namespace then changes what runs.

agentgarm mcp registry pin io.github.example-org/weather --version 1.4.0
security_boundaries:
  mcp:
    allow:
      # Resolved at each launch from the registry snapshot Central delivered:
      # the package, its exact version and its integrity all come from the snapshot.
      - registry: io.github.example-org/weather
        version: "1.4.0"
        id: weather
        namespace_kinds: [github]
    servers:
      # Settings for the registry server above: never a package or url.
      - id: weather
        sandbox: { egress_hosts: ["api.weather.example"] }

See also

Run MCP servers through the gateway

List the MCP servers an agent may use, pinned to a package and hash, and run each through the gateway, where agentgarmd decides every tool call first.

6. Withdraw a version

Set the status of one of your org's own versions with registry server status; a mirrored version's status follows the next import. Central Lite signs the next snapshot, and once a machine installs it, a registry name resolving to a deleted version is refused at launch, even when the policy names that exact version; a deprecated one launches with an alert. Without a snapshot that verifies (none installed, an expired one, or one older than the last) no registry name resolves, and those servers do not launch.

garm-central registry server status com.example.private/server-one 2.0.0 deleted --message "Replaced by 2.1.0"