Core Concepts

This page introduces the foundational concepts behind MCP Registry. Understanding these concepts is essential before working with the publish, resolve, or download protocols.

Artifacts

An artifact is any stored blob identified by its content digest. The registry stores three kinds of artifacts:

Artifacts are content-addressed: their identifier is a SHA-256 digest of the content. The same content always produces the same digest, which enables deduplication and integrity verification.

Artifact Addressing

Every artifact is addressed by its digest in the format sha256:<hex>. For example:

sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

This digest acts as both the unique identifier and the integrity commitment. If a single byte of the artifact changes, the digest changes.

Manifests

The manifest is the contract between a publisher and an executor. It declares what a bundle contains, what runtime it requires, how to start it, and what resources it needs.

A manifest is a JSON document following a versioned schema. The current schema version is 1.

{
  "schema_version": 1,
  "package": {
    "id": "acme/weather-service",
    "version": "1.0.0",
    "description": "Weather data service providing current conditions",
    "license": "Apache-2.0"
  },
  "runtime": {
    "type": "node",
    "version": ">=18.0.0"
  },
  "entrypoint": {
    "command": ["node", "dist/index.js"],
    "env": {
      "NODE_ENV": "production"
    }
  },
  "permissions": {
    "network": {
      "outbound": ["api.weather.com:443"],
      "inbound": false
    },
    "env_vars": ["WEATHER_API_KEY"]
  },
  "resources": {
    "memory_mb": 256,
    "cpu_millicores": 100
  }
}

Key Manifest Sections

package – Identification metadata: the full package ID (org/name), version, description, license, authors, and keywords.

runtime – Execution environment requirements. Supported types are node, python, oci, and binary. Each type has specific sub-fields (e.g., version for interpreters, image for OCI containers, platform for binaries).

entrypoint – How to start the MCP: the command array, optional arguments, environment variables, and working directory.

permissions – Declared permissions the MCP requires: network access patterns, filesystem paths, environment variable names, and Linux capabilities. These are declarations, not enforcement mechanisms. Executors decide whether to trust them.

resources – Resource requirements and limits: memory (MB), CPU (millicores), execution timeout, and maximum concurrent instances.

healthcheck – Optional health monitoring configuration: endpoint path, check interval, and timeout.

metadata – Arbitrary key-value pairs for custom organizational needs.

Bundles

A bundle is a tar.gz archive containing the MCP implementation. The contents depend on the runtime type:

• Node.js: Compiled JavaScript, package.json, and package-lock.json
• Python: Source modules, requirements.txt
• OCI: Configuration files (the container image is referenced in the manifest)
• Binary: Compiled executable for the target platform

Bundles are immutable once published. Their content is bound to a specific SHA-256 digest, and that digest is recorded in the version record. Any modification to the bundle would produce a different digest.

Content-Addressed Storage

All artifacts in MCP Registry are stored and retrieved by their SHA-256 content digest. This design provides three guarantees:

1. Automatic deduplication – If two versions reference the same bundle, only one copy is stored.
2. Integrity verification – Clients can compute the digest of downloaded artifacts and compare it against the expected value from the resolution response.
3. Immutability – Changing the content of an artifact changes its digest, making silent modification impossible.

The digest format is always sha256:<64-character-hex-string>.

Verification Flow

Publisher                    Registry                    Client
    |                           |                          |
    | Upload artifact           |                          |
    | with digest sha256:abc... |                          |
    |-------------------------->|                          |
    |                           | Store by digest          |
    |                           |                          |
    |                           |      Resolve: get digest |
    |                           |<-------------------------|
    |                           |      digest: sha256:abc  |
    |                           |------------------------->|
    |                           |                          |
    |                           |      Download artifact   |
    |                           |<-------------------------|
    |                           |      artifact bytes      |
    |                           |------------------------->|
    |                           |                          |
    |                           |   Compute SHA-256(bytes) |
    |                           |   Compare with sha256:abc|
    |                           |   Match = integrity OK   |

Version Lifecycle

Every version in the registry moves through a defined set of states. State transitions are explicit and intentional – they never happen automatically.

                +---------+
                |  draft  |
                +----+----+
                     | (finalize)
                     v
                +---------+
     +--------->| ingested|<----------+
     |          +----+----+           |
     |               |                |
  (republish)   (upload ok)    (policy fail)
     |               |                |
     |               v                v
     |          +---------+    +-------------+
     |          |published|    | quarantined |
     |          +----+----+    +-------------+
     |               |
     |          (revoke)
     |               |
     |               v
     |          +---------+
     +----------| revoked |
                +---------+

States

draft – A work-in-progress version that has not been finalized. Draft versions are not visible in normal resolution queries and can only be accessed with the mcp:resolve:prepublish scope. Drafts may be modified or deleted.

ingested – The initial state after a publish request is accepted. The version record exists in the database, but the bundle upload may not yet be complete (when using presigned URLs). Ingested versions are not visible in normal resolution queries.

published – The version is available for resolution and download. Published versions appear in resolution queries, can be downloaded by authorized clients, and are immutable – their artifacts cannot be changed.

quarantined – The version was rejected by repository policy validation. Quarantined versions exist in the database but are not resolvable. They include a record of why they were quarantined and can be reviewed by administrators.

revoked – The version has been withdrawn. Revoked versions are not resolvable and remain in the database for audit purposes. They cannot be un-revoked – to fix an issue, publish a new version instead.

Valid Transitions

Evidence Artifacts

Evidence artifacts are additional attestation materials attached to a version. They complement the manifest and bundle with independently verifiable information.

Common evidence types include:

Evidence artifacts are stored the same way as manifests and bundles – by content digest. They are referenced in the version record via evidence_digests and are accessible through the artifacts API.

Evidence is optional but strongly recommended for production deployments. It enables downstream consumers to make informed trust decisions without relying solely on the manifest.

Organizations

An organization is a namespace for packages. Every package belongs to exactly one organization, and the full package identifier takes the form {org}/{name}.

Organizations provide:

• Namespace isolation – Package names only need to be unique within an organization
• Access control – Permissions and scopes are granted per organization
• Member management – Users can be added to organizations with specific roles

Organization Properties

Packages Within Organizations

Each package within an organization has:

• Visibility – public (visible to unauthenticated catalog queries if enabled) or private (requires authentication for all operations)
• Tags – Arbitrary labels for categorization and search
• Default Policy Ref – Optional reference to a policy document governing execution

Separation of Concerns

The registry explicitly separates responsibilities across components:

What the Registry Does

• Stores artifacts by content digest
• Indexes packages and versions
• Enforces access control (authentication and authorization)
• Validates repository policies
• Provides the resolution protocol
• Maintains an audit trail

What the Registry Does Not Do

• Clone repositories – The registry never fetches source code
• Build artifacts – Bundles must be pre-built by pipelines
• Execute code – The registry stores but never runs artifacts
• Provide sandboxing – Runtime isolation is the executor’s responsibility
• Scan artifacts – Security scanning is delegated to external tools (e.g., mcp-scan)

This separation keeps the registry simple, auditable, and secure. Each component in the pipeline is responsible for its own domain.

Immutability

The following are immutable once created:

• Artifact content – A digest always refers to the same bytes
• Published version metadata – Version string, digests, and repository info cannot be changed
• Audit log entries – All logged actions are append-only

The following can change:

• Version status – Can transition through lifecycle states
• Package metadata – Visibility, description, tags, and default policy can be updated
• Organization metadata – Display name can be updated