How the Registry Works

mpak’s registry connects publishers (who build MCP servers and skills) with consumers (who run them). Here’s how the pieces fit together.

Architecture Overview

Publishing:

┌──────────────┐     ┌──────────────────┐     ┌──────────────────┐
│  Your Repo   │────►│  GitHub Actions   │────►│  GitHub Release  │
│  + manifest  │     │  (mcpb-pack)      │     │  (.mcpb asset)   │
└──────────────┘     └────────┬─────────┘     └──────────────────┘
                              │
                              │ OIDC token + metadata
                              ▼
                     ┌──────────────────┐
                     │  mpak Registry   │
                     │  (metadata only) │
                     └──────────────────┘

Consuming:

┌──────────────┐     ┌──────────────────┐     ┌──────────────────┐
│  mpak CLI    │────►│  mpak Registry   │────►│  GitHub Release  │
│  search/run  │     │  (resolve pkg)   │     │  (download .mcpb)│
└──────────────┘     └──────────────────┘     └──────────────────┘
       │
       ▼
┌──────────────┐
│  ~/.mpak/    │
│  cache/      │
│  (extract    │
│   + run)     │
└──────────────┘

The Publishing Flow

Add a manifest to your repo

Create manifest.json describing your MCP server (name, version, how to run it).
Add the GitHub Action

Add the mcpb-pack action to .github/workflows/release.yml with id-token: write permission.
Create a GitHub Release

Tag your code and publish a release on GitHub.
The action builds the bundle

mcpb-pack vendors all dependencies into a .mcpb file (a zip archive).
The action uploads to your release

The .mcpb file is attached as a GitHub Release asset. You retain full control of the artifact.
The action announces to mpak

Using a GitHub OIDC token, the action tells the registry: “this package exists, here’s the metadata, here’s where to download it.”
The registry verifies and records

mpak verifies the OIDC token against GitHub’s public keys, confirms the scope matches the GitHub owner, and stores the metadata.

The registry never stores your bundle. It stores metadata: name, version, description, download URL, provenance claims, and certification results.

The Download Flow

User searches or runs

mpak bundle search postgres queries the registry API. mpak bundle run @org/server triggers a resolve-and-run.
CLI queries the registry

The CLI calls the registry API to resolve the package name to metadata, including the download URL pointing to a GitHub Release asset.
CLI downloads the bundle

The .mcpb file is downloaded directly from GitHub Releases (not from mpak’s servers).
CLI extracts and caches

The bundle is extracted to ~/.mpak/cache/<scope>/<name>/<version>/. Subsequent runs use the cache.
CLI runs the server

The server starts using the vendored dependencies inside the bundle. No system-level installation needed.

Where Bundles Are Stored

Bundles are stored as GitHub Release assets, not on mpak’s servers. The registry stores metadata only. This means:

Concern	How It’s Handled
CDN / bandwidth	GitHub handles distribution globally
Availability	Bundles are as available as GitHub
Control	Publishers retain full control of their artifacts
Cost	No storage costs on mpak’s side
Deletion	Deleting a GitHub Release removes the bundle

Security Model

Every layer of the registry is designed around trust and verification:

Authentication: Publishing uses GitHub OIDC, not API keys. No secrets to leak.
Scope enforcement: Your GitHub org/username determines your package scope. Cryptographically enforced. See Naming Conventions.
Provenance: Every bundle has a verifiable chain from source code to published artifact. See Provenance.
Certification: Bundles are automatically scanned against the mpak Trust Framework. See Certification.
Access: The registry is public. See Access Model.

Next Steps

API Reference Programmatic access to the registry

Access Model Authentication, authorization, and scope enforcement

Publishing Step-by-step publishing guide

Provenance Cryptographic proof of bundle origin