A pattern repeats itself in every enterprise software adoption cycle. The technology works. The pilot succeeds. And then, somewhere around the third meeting with the security architecture review board, the question arrives:
"Where is the registry hosted, who controls it, and what happens if it goes down?"
The honest answer for most AI tool ecosystems today is: a single public registry, controlled by a single organisation, with a single point of failure. If it goes down, tool discovery and installation stop. If it's compromised, every consumer is exposed. If the controlling organisation changes its terms, every publisher is affected.
Enterprise teams have learned — from npm outages, from Docker Hub rate limits, from PyPI's occasional unavailability — that depending on a single registry is an operational risk they'd rather not carry into production. But the alternative — forking the ecosystem and running a completely isolated private registry — means losing access to the public tool catalog and fragmenting the developer experience.
MPP's federation model is designed to resolve this tension.
What Federation Means
Federation is a model where multiple independent registries can discover and resolve packages from each other, without any single registry being authoritative over the entire ecosystem.
Each registry is sovereign: it has its own domain, its own storage, its own publisher base, its own policies. But through a standardised discovery protocol, registries can query each other to find packages that aren't available locally.
The analogy is email. You run your own mail server (or use a hosted one). You control your own users and policies. But you can send and receive messages with any other mail server on the internet, because everyone speaks SMTP. No single server controls the ecosystem.
MPP federation works the same way. Each registry speaks the MPP federation protocol. Each registry controls its own packages. And any registry can resolve packages from any other registry it trusts.
The Discovery Protocol
Federation starts with discovery. Every MPP registry exposes a well-known endpoint:
GET /.well-known/mpp-federation
This returns the registry's federation identity:
{
"registry_id": "registry.example.com",
"public_key": "<base64-ed25519-public-key>",
"api_version": "1.0",
"capabilities": ["mirror", "relay", "announce"],
"peers_endpoint": "/api/v1/federation/peers"
}
The response includes:
registry_id: A unique identifier for this registry (typically its domain name).public_key: The registry's Ed25519 public key. This is used to verify that federation messages come from the claimed registry.api_version: The federation protocol version. Registries with incompatible versions can detect this before attempting interoperation.capabilities: Which federation modes this registry supports.peers_endpoint: Where to find the list of registries this one federates with.
Discovery is lightweight and cacheable. A registry checks the /.well-known/mpp-federation endpoint of a potential peer once, verifies the response, and stores the peer's identity. Subsequent interactions use the stored identity.
The Three Trust Levels
Not all federation relationships are equal. An organisation's private registry federating with the official public registry is a fundamentally different trust relationship than two public registries mirroring each other's catalogs.
MPP defines three federation trust levels, each with different data flow characteristics:
Mirror
Registry A ←→ Full Sync ←→ Registry B
Mirror is full replication. Registry A maintains a complete copy of Registry B's package catalog (and optionally vice versa). Packages are synced periodically — new versions, yanked versions, and metadata updates all flow between the two registries.
When to use it:
- Air-gapped environments. An organisation that cannot allow runtime network access to external registries mirrors the public registry to an internal server. Agents resolve packages locally with no outbound connections.
- Geographic distribution. A global organisation mirrors a single primary registry to regional replicas for low-latency access.
- Resilience. If the primary registry goes down, the mirror continues serving all packages.
The cost of mirroring is storage and bandwidth. A full catalog replica requires significant disk space, and ongoing synchronisation generates network traffic proportional to the ecosystem's publishing rate.
Relay
Client → Registry A → (query forwarded) → Registry B → Response
Relay is forwarded search. When a client queries Registry A for a package that isn't available locally, Registry A forwards the query to its relay peers. If a peer has the package, the response flows back through Registry A to the client.
When to use it:
- Private registries with public fallback. An organisation runs a private registry for internal tools. When an agent requests a public tool, the private registry relays the request to the public registry. The organisation controls all inbound traffic through its own server.
- Selective caching. Registry A doesn't replicate the entire public catalog, but it caches packages that are requested through relay. Over time, frequently-used packages accumulate locally.
- Policy enforcement. The relaying registry can apply its own policies before forwarding — for example, only relaying packages that match a whitelist of publisher keys or package name patterns.
Relay is the most common federation mode for enterprise deployments. It provides access to the public ecosystem without requiring full replication, and it gives the enterprise registry operator a control point for policy enforcement.
Announce
Registry A → (metadata only) → Registry B
Announce is the lightest-weight federation mode. Registry A tells Registry B that a package exists (package ID, version, publisher), but does not transfer the package data. If a client on Registry B wants the announced package, they are redirected to Registry A to download it.
When to use it:
- Ecosystem visibility. A private registry announces its packages to the public ecosystem so that external teams know they exist — but the packages themselves are only available from the private registry, behind authentication.
- Catalog aggregation. A meta-registry aggregates announcements from many registries to provide a unified search interface, without storing any package data itself.
- Bandwidth conservation. Registries with limited bandwidth can announce their catalog without committing to serving downloads for the entire ecosystem.
Cross-Registry Resolution
When a client requests a package that doesn't exist on the local registry, federation resolution kicks in:
Client → Registry A (local lookup: not found)
→ Registry A queries peer Registry B (relay)
→ Registry B has it → Response (hops: 1)
If Registry B doesn't have it either but has its own peers:
Client → Registry A → Registry B → Registry C → Found (hops: 2)
The maximum hop count is 3. This is a hard limit designed to prevent resolution loops and unbounded query propagation. Three hops covers the most common topology:
Private Registry → Public Registry → Specialised Registry
The resolution response includes the number of hops, letting the client understand where the package was ultimately found:
{
"found": true,
"package_id": "org.acme.sql-analyzer",
"registry": "https://public-registry.example.com",
"latest_version": "1.2.0",
"hops": 1
}
The hop count is operationally useful: if a package that previously resolved in 0 hops (local) suddenly requires 2 hops, something has changed in the federation topology that warrants investigation.
Enterprise Deployment Patterns
Pattern 1: Private Registry with Public Relay
The most common enterprise pattern. The organisation runs a private registry for internal tools and relays to the public registry for everything else.
┌─────────────────────┐ ┌──────────────────────┐
│ Private Registry │ ──relay──▶ Public Registry │
│ registry.corp.com │ │ registry.mpp.dev │
│ │ │ │
│ Internal tools: │ │ Public tools: │
│ • org.corp.db-tool │ │ • io.github.*.* ... │
│ • org.corp.deploy │ │ │
└─────────────────────┘ └──────────────────────┘
▲
│
Agent hosts
All agent traffic goes to registry.corp.com. Internal tools resolve locally. Public tools are relayed to the public registry through the private registry's controlled gateway. The security team can:
- Whitelist specific public packages or publishers
- Block packages that fail internal security review
- Cache approved public packages locally for resilience
- Audit all package resolution through their own infrastructure
Pattern 2: Air-Gapped Mirror
For environments with no internet access — classified networks, regulated infrastructure, operational technology networks:
┌──────────────────────┐ (offline sync) ┌──────────────────┐
│ Public Registry │ ──────────────────▶ │ Internal Mirror │
│ registry.mpp.dev │ (periodic export) │ registry.airgap │
│ │ │ │
└──────────────────────┘ └──────────────────┘
▲
│
Agent hosts
(no internet access)
A synchronisation process exports packages from the public registry to a transfer medium (encrypted USB, secure file transfer). The internal mirror imports the packages. Agents resolve everything locally.
The mirror maintains full signature verification: packages imported from the public registry are verified against their original signatures. The air-gapped environment doesn't need to trust the transfer process — it trusts the cryptographic signatures.
Pattern 3: Multi-Registry Enterprise
Global organisations with multiple divisions, each with their own tool ecosystems:
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Engineering │ │ Finance │ │ Healthcare │
│ Registry │ │ Registry │ │ Registry │
│ (relay → pub) │ │ (mirror pub) │ │ (announce) │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
└───────────────────┼───────────────────┘
│
┌──────▼───────┐
│ Central │
│ Registry Hub │
│ (relay → all) │
└──────────────┘
Each division runs its own registry with its own policies. A central hub federates with all divisional registries, providing a unified search interface. The healthcare division uses announce-only federation (packages remain on the healthcare registry, behind HIPAA-compliant access controls). The finance division mirrors the public registry for resilience. Engineering relays to the public registry directly.
Each registry can have different:
- Trusted publisher keys
- Package approval workflows
- Privacy filter requirements
- HITL confirmation thresholds
Federation connects the ecosystems. Policy separation keeps them appropriate to their regulatory and risk contexts.
Registry Identity and Trust
Each registry has its own Ed25519 keypair. The public key is published at the /.well-known/mpp-federation endpoint. This key serves two purposes:
-
Peer Authentication. When Registry A queries Registry B, Registry B can verify that the request comes from a registry whose public key it recognises. This prevents unknown registries from querying the federation network.
-
Response Integrity. Federation responses can be signed by the responding registry, allowing the originating registry to verify that the response hasn't been tampered with in transit.
Adding a federation peer requires administrator action:
curl -X POST https://registry.corp.com/api/v1/federation/peers \
-H "Authorization: Bearer mpp_admin_token" \
-H "Content-Type: application/json" \
-d '{
"origin": "https://registry.mpp.dev",
"public_key": "<base64-encoded-public-key>",
"trust_level": "relay"
}'
This is deliberate. Federation is not automatic discovery. An administrator explicitly chooses which registries to federate with, at which trust level, and peers can be removed at any time. Federation is a policy decision, not a technical default.
Operational Considerations
Monitoring
Federation adds monitoring requirements beyond a standalone registry:
| Metric | What It Indicates | |--------|-------------------| | Peer response latency | Network health between registries | | Relay resolution rate | How often local resolution fails and relay is needed | | Hop count distribution | Whether the federation topology is efficient | | Peer availability | Whether federated registries are reachable | | Cache hit rate | Whether caching is reducing relay traffic |
A rising relay resolution rate may indicate that internal packages are being moved or renamed. An increasing average hop count may indicate that a peer has lost connectivity with its own peers.
Failure Modes
Federation is designed to degrade gracefully:
- Peer unreachable. If a relay peer is down, the query returns "not found" to the client. The local registry continues serving its own packages. There is no cascading failure.
- Peer slow. Federation queries have configurable timeouts. A slow peer results in a "not found" response, not a hung client.
- Peer compromised. Because all packages carry their original publisher signatures, a compromised peer cannot serve tampered packages without detection. The client-side Gatekeeper verifies signatures regardless of which registry the package came from.
The key architectural property: federation failure is local. A broken peer affects resolution of packages sourced from that peer. It does not affect local packages, packages from other peers, or the registry's core functionality.
Storage Planning
| Mode | Storage Requirement | |------|-------------------| | Mirror | Full catalog replica (~size of public registry) | | Relay | Cached packages only (~size of frequently used subset) | | Announce | Metadata only (~negligible) |
For relay mode, implementing an LRU cache with a configurable maximum size prevents unbounded storage growth. Packages evicted from the cache are re-fetched on the next request.
Why Not Just Run a Proxy?
Some teams consider running an HTTP proxy or CDN cache in front of the public registry rather than implementing proper federation. This works for basic resilience but misses the critical features:
- No policy control. A proxy forwards all requests. Federation allows selective relay based on package attributes, publisher keys, or internal approval status.
- No local packages. A proxy only serves what the upstream has. Federation lets the private registry host its own packages alongside proxied public ones.
- No topology flexibility. A proxy is point-to-point. Federation supports multi-hop resolution, announce-only relationships, and complex enterprise topologies.
- No identity. A proxy has no registry identity. Federation peers authenticate each other and can make trust decisions based on registry identity.
A proxy is a caching layer. Federation is an interoperability protocol.
The Federation Endgame
The long-term vision for MPP federation is an ecosystem of interoperating registries — analogous to the federated email network — where:
- Organisations run their own registries for internal tools
- Public registries serve the open-source community
- Specialised registries serve domain-specific tool ecosystems (healthcare, finance, legal)
- Meta-registries aggregate and search across the ecosystem
- Every registry enforces its own policies while maintaining interoperability
No single entity controls the namespace. No single server is a single point of failure. No single compromise affects the entire ecosystem. This is the decentralised trust model that enterprise AI tooling needs.
For the registry API details, see the Registry API Reference. For deployment instructions, see the Registry Deployment Guide. For how federation relates to the broader security model, read Defence in Depth for AI Agents (coming soon).