Study usage of MCPB for bundling

[ContextVM-org]

https://github.com/modelcontextprotocol/mcpb

[abhayguptas]

Research Findings & Implementation Plan

Background

MCPB (MCP Bundles) is a packaging format by Anthropic for distributing local MCP servers. An .mcpb file is a ZIP archive containing the server code, dependencies, and a manifest.json. Compatible hosts (like Claude Desktop) can install them with a single click — read the manifest, prompt the user for config, and spawn the server process.

• Spec: https://github.com/modelcontextprotocol/mcpb
• Manifest spec: MANIFEST.md
• CLI docs: CLI.md

Key Observations

MCPB is stdio-only and local. The host spawns the server as a child process and communicates over stdin/stdout. There is no concept of remote or networked servers in the spec.

CVM servers use Nostr transport. But the Gateway already bridges this gap — it wraps any stdio MCP server and exposes it over Nostr with zero code changes. This means we can fully reuse the MCPB format by having cvmi serve handle the Nostr layer on top.

MCPB reserves _meta for third-party extensions. We can define a _meta.com.contextvm namespace for CVM-specific configuration (relays, encryption, public/private mode, pricing) without breaking MCPB compatibility.

Architecture

The user decides how to run a bundle. No dual mode needed.

Developer workflow:
  Build MCP server → cvmi pack → distributes .mcpb

User workflow (option A - local stdio):
  Any MCPB host → installs bundle → runs via stdio (standard MCPB)

User workflow (option B - CVM over Nostr):
  cvmi serve my-server.mcpb → reads manifest + CVM config → runs on Nostr

CVM Manifest Convention (Draft)

Standard MCPB manifest with CVM-specific fields under _meta.com.contextvm:

{
  "manifest_version": "0.3",
  "name": "example-cvm-server",
  "display_name": "Example CVM Server",
  "version": "1.0.0",
  "description": "An example server packaged for CVM distribution",
  "author": {
    "name": "Developer Name"
  },
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/index.js"]
    }
  },
  "_meta": {
    "com.contextvm": {
      "public": true,
      "default_relays": [
        "wss://relay.damus.io",
        "wss://nos.lol"
      ],
      "encryption": "nip44",
      "announce": true,
      "pricing": null
    }
  }
}

Fields under _meta.com.contextvm:

Field	Type	Description
public	boolean	Whether the server accepts connections from any pubkey
default_relays	string[]	Default relay URLs for announcing and communication
encryption	string	Encryption mode: nip44, optional, disabled
announce	boolean	Whether to publish server announcements (kind 11316-11320)
pricing	object/null	CEP-8 pricing config, null if free

All of these are defaults. cvmi serve can override any of them via CLI flags, env vars, or the cvmi config file using the existing precedence chain.

Implementation Plan

Phase 1: Define the CVM manifest convention

• Finalize the _meta.com.contextvm schema
• Document it properly

Phase 2: cvmi pack command

• New subcommand that generates a valid .mcpb bundle
• Reads the project directory, prompts for CVM-specific config (or reads from existing manifest)
• Injects _meta.com.contextvm fields into the manifest
• Packages everything into a .mcpb archive (ZIP with max compression)
• Validates the manifest against both MCPB and CVM schemas before packing
• Excludes dev files (.git, .cache, .DS_Store, etc.)

Phase 3: cvmi serve reads bundles

• Extend cvmi serve to accept a .mcpb file as input
• Extracts the bundle, reads manifest + CVM config
• Uses CVM defaults from manifest, applies runtime overrides
• Spawns the server and wraps it with the Gateway as usual

Phase 4: Marketplace foundations (future)

• Registry/catalog where developers can publish .mcpb bundles
• Discovery via the website or CLI (cvmi discover already exists)
• Think Umbrel/Start9 but for MCP servers on Nostr

Open Items

• Finalize the _meta.com.contextvm schema — are there fields I'm missing?
• Should cvmi pack also support user_config generation for things like API keys the server might need?
• How should pricing config be structured? Follow CEP-8 directly?
• Should we support Python/binary server types from day one, or start with Node.js only?

[abhayguptas]

Hi, @ContextVM-org! Take a look once.

[ContextVM-org]

We're exploring how to bundle CVM servers so users can download and deploy them with ease — essentially a marketplace of MCP servers on Nostr. Our starting point is the MCPB (MCP Bundles) format by Anthropic: a .mcpb file is a ZIP archive containing server code, dependencies, and a manifest.json. Compatible hosts can install them with a single click.

MCPB is stdio-only and local. CVM servers use Nostr transport. The question is: how do we bridge this gap?

We are thinking about two bundle types:

stdio bundles — The server communicates over stdin/stdout. cvmi serve spawns the process and wraps it with the Gateway. The Gateway owns all CVM configuration (relays, encryption, announcements, payments). The server is completely transport-agnostic.

Native CVM bundles — The server uses the CVM SDK's NostrServerTransport directly. This is desirable when the server needs SDK-specific features like injectClientPubkey, dynamic authorization callbacks, or other transport-level capabilities that the Gateway can't provide.

The tension: for stdio bundles, configuration is straightforward — the Gateway handles everything. For native CVM bundles, the server already configures its own transport. How do we inject runtime configuration (relays, encryption, pricing, etc.) from the bundle manifest?

The Env Var Contract

The idea is to use environment variable contract that's language-agnostic and puts config ownership in the server author's hands.

How it works:

1. The server author declares which CVM config fields their server accepts, mapped to env var names, in the manifest's _meta.com.contextvm.env_mapping
2. cvmi serve reads CVM configuration from its standard precedence chain (CLI flags → config file → manifest defaults)
3. cvmi serve injects the resolved values as environment variables using the declared mapping
4. The server reads those env vars and configures its transport accordingly

Example manifest for a native CVM server:

{
  "manifest_version": "0.3",
  "name": "my-cvm-server",
  "version": "1.0.0",
  "description": "A CVM-native server with pubkey injection",
  "author": { "name": "Developer" },
  "server": {
    "type": "node",
    "entry_point": "server/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/index.js"]
    }
  },
  "_meta": {
    "com.contextvm": {
      "transport": "cvm",
      "env_mapping": {
        "relays": "CVM_RELAYS",
        "encryption": "CVM_ENCRYPTION",
        "public": "CVM_PUBLIC",
        "private_key": "CVM_PRIVATE_KEY",
      },
      "defaults": {
        "relays": ["wss://relay.contextvm.org", "wss://relay.damus.io"],
        "encryption": "optional",
        "public": true,
      }
    }
  }
}

Why this works:

• Language-agnostic — env vars are universal (Node, Python, Rust, Go, etc.)
• Server author owns the contract — they declare what they accept, not the SDK
• No SDK cooperation required — just standard env var reading
• Clean separation — cvmi serve handles config resolution and injection, the server handles transport logic
• Flexible — a server can accept any subset of CVM config fields

---

The transport Field

"_meta": {
  "com.contextvm": {
    "transport": "stdio"
  }
}

Value	cvmi serve behavior
"stdio" (default)	Spawns process, wraps with Gateway. Gateway owns all CVM config.
"cvm"	Spawns process directly, injects env vars per env_mapping. No Gateway.

stdio is the simplest path — ideal for generic MCP servers that don't need CVM-specific transport features. cvm enables advanced SDK features like injectClientPubkey, dynamic authorization callbacks (isPubkeyAllowed), and other transport-level capabilities.

---

Docker Support

Both Start9 and Umbrel use Docker as their fundamental bundling engine. We can adopt the same approach without breaking the MCPB format.

Proposal: Add server.type = "docker" to the manifest. The .mcpb contains a reference to a Docker image (not the image itself), and mcp_config defines how to run it:

{
  "server": {
    "type": "docker",
    "image": "ghcr.io/developer/my-cvm-server:1.0.0",
    "mcp_config": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/developer/my-cvm-server:1.0.0"]
    }
  }
}

The Docker container exposes stdio MCP (the standard MCPB contract). cvmi serve spawns docker run --rm -i <image> and communicates over stdio, then wraps with the Gateway as usual. The image is pulled from a registry on first run.

For multi-container setups (server + database + cache), include a docker-compose.yml in the bundle:

{
  "server": {
    "type": "docker",
    "compose_file": "docker-compose.yml",
    "mcp_config": {
      "command": "docker",
      "args": ["compose", "-f", "${__dirname}/docker-compose.yml", "run", "--rm", "-i", "server"]
    }
  }
}

Key Takeaways

1. MCPB is the right base format — simple zip, well-specified, growing ecosystem. We extend it via _meta.com.contextvm without breaking compatibility.

2. Two transport modes — stdio (gateway-wrapped, simplest) and cvm (native Nostr transport, for servers that need SDK-specific features).

3. The env var contract is the bridge for native CVM bundles — language-agnostic, server-author-controlled, no SDK cooperation required.

4. Docker is a natural fit for complex deployments — reference images in the manifest, pull on first run, run via stdio.

[abhayguptas]

This makes a lot of sense. The stdio vs cvm transport split is the right call because wrapping a native CVM server with the Gateway would just create conflicts. The env var contract is clean, it keeps things language-agnostic and lets the server author control what they accept without us having to standardize anything on the SDK side. Docker support is also a natural fit, especially for servers that need databases or other services alongside them.

I have already started working on aligning the implementation with this. Updated the manifest schema to use the transport field, nested defaults, and env_mapping. Also added the dual-mode branching in serve so stdio bundles go through the Gateway and cvm bundles get spawned directly with the injected env vars. Will push the updated PR shortly.

[1amKhush]

the implementation is solid (interactive wizard, config precedence, Zod validation, cleanup on shutdown), just a few things to address:

1. Schema hasn't caught up with the updated architecture

The PR still uses the original flat schema:

// Current PR
CVMMetaSchema = z.object({
  public: z.boolean(),
  default_relays: z.array(z.string()),
  encryption: z.enum(['nip44', 'optional', 'disabled']),
  announce: z.boolean(),
  pricing: z.any().nullable(),
});

Needs to reflect transport, env_mapping, and nested defaults from @ContextVM-org's updated spec. A discriminated union on transport would be clean:

const CVMMetaSchema = z.discriminatedUnion('transport', [
  z.object({
    transport: z.literal('stdio').default('stdio'),
    defaults: z.object({ relays: ..., encryption: ..., public: ..., announce: ..., pricing: ... }),
  }),
  z.object({
    transport: z.literal('cvm'),
    env_mapping: z.record(z.string(), z.string()),
    defaults: z.object({ ... }),
  }),
]);

2. Encryption enum mismatch

The manifest uses nip44 but the SDK's EncryptionMode uses required. This creates a mapping step that'll bite you later — if a future encryption scheme replaces NIP-44, you'd have to deprecate a manifest field name. Just use the SDK values directly: optional / required / disabled.

3. display_name is required in the schema but optional in MCPB

display_name: z.string(), // will reject valid third-party MCPB bundles

Should be z.string().optional().

4. mcp_config.env is missing from the schema

The MCPB spec supports env in mcp_config — Python bundles need this for PYTHONPATH. The schema should include it:

mcp_config: z.object({
  command: z.string(),
  args: z.array(z.string()).optional(),
  env: z.record(z.string(), z.string()).optional(),
}),

And serve.ts should merge mcp_config.env into the spawn environment with ${__dirname} substitution applied.

5. Missing uv server type

MCPB spec (v0.3+) supports server.type = "uv". The Zod enum currently only allows node | python | binary.

Overall imo this is heading in the right direction, just some tweaks needed :)

[harsh04044]

Really like where this is headed, the env var contract especially. Keeping config language-agnostic and in the server author's hands is the right call. One thing that falls out of that: _meta is the only open extension point, so anything custom has to nest under it.

A few things I'd flag:

1. A transport: "cvm" bundle won't run in a normal MCPB host

MCPB bundles are meant to install in any standard host with one click (option A). A cvm bundle gives that up: it's a valid .mcpb that only actually works under cvmi serve. Drop it into a standard MCPB host and that host ignores _meta.com.contextvm, spawns mcp_config.command/args expecting stdio, and the server comes up on NostrServerTransport instead and never writes to the pipe, so it just hangs.

I don't think we have to live with that. If the transport is picked by an injected env var, the same bundle works in both:

const transport = process.env.CVM_TRANSPORT === "cvm"
  ? new NostrServerTransport({ /* relays/signer from injected CVM_* env */ })
  : new StdioServerTransport();
await server.connect(transport);

stdio in a standard host, native Nostr when cvmi serve sets CVM_TRANSPORT=cvm. You lose the SDK-specific bits (injectClientPubkey etc.) in stdio mode but that's expected. For servers that genuinely can't run without a client pubkey, I'd mark them cvm-only on purpose rather than ship something that silently hangs everywhere except cvmi serve. Either way it's worth deciding explicitly: are cvm bundles meant to be cvmi-only, or installable everywhere?

2. server.type = "docker" won't validate

server is additionalProperties: false, type is enum-only, and entry_point is required, so type:"docker" + image + compose_file trips all three against the schema mcpb pack enforces. Easy to keep it legal though. Move the docker bits into our namespace and let mcp_config do the running:

"server": {
  "type": "binary",
  "entry_point": "run-docker.sh",        // nominal, schema wants it; mcp_config does the work
  "mcp_config": { "command": "docker", "args": ["run","--rm","-i","ghcr.io/dev/srv:1.0.0"] }
},
"_meta": { "com.contextvm": { "docker": { "image": "ghcr.io/dev/srv:1.0.0", "compose_file": "docker-compose.yml" } } }

Worth keeping in mind too: a docker bundle isn't self-contained (image pulls at runtime) and needs Docker on the box, both of which cut against the one-click promise. Great for cvmi serve, rough for a desktop end user.

3. Keep secrets in user_config, not the env_mapping contract

On the open question about API keys, I'd say yes to generating user_config, and keep it separate from env_mapping. Two injection paths doing different jobs:

• the native MCPB one that works in any host: user_config (sensitive: true → OS keychain) → ${user_config.x} → mcp_config.env. That's where user-supplied stuff belongs: the server's nsec, upstream API keys.
• our _meta.env_mapping, which only cvmi serve reads: keep that for CVM config we resolve ourselves (relays, encryption, public).

Mainly I'd keep secrets out of _meta.defaults, since a default there ships a plaintext value inside the zip. Small thing on the env_mapping side: mcp_config.env is typed string → string, so we need a serialization rule: relays comma-joined (matches how cvmi already parses CVMI_*_RELAYS), public as "true", pricing as JSON.

Overall I think this is the right base to build on, just these few bits to sort out :)

[abhayguptas]

Thanks for the reviews, both of you. Really helpful.

Kush, point 1 about the flat schema was already fixed in the latest commit before your review, we restructured it to use transport, env_mapping, and nested defaults. But the other four were solid catches. Just pushed a fix for all of them: encryption enum now uses required/optional/disabled to match the SDK directly, display_name is optional per MCPB spec, added mcp_config.env support with __dirname substitution, and added uv as a server type for v0.4+ compatibility.

Harsh, the three points you raised are more on the architecture side so I want to loop in the @ContextVM-org before making changes there. Specifically whether cvm bundles should be cvmi-only or portable, whether docker should be a first class server type or live under our _meta namespace to stay spec compliant, and whether private_key belongs in env_mapping or in user_config with sensitive: true. All fair points but they touch the contract design that the mentor laid out, so want his take before we move on those.

Appreciate the thorough reviews from both of you.

[ContextVM-org]

Thanks, everyone, for your reviews. I'm going to respond to you. But @abhayguptas, maybe we can hold off on the implementation until we get the design right? Especially to avoid double work. Up to you.

@1amKhush, great points, thanks for the feedback.

Aside from that, and answering @harsh04044. I think we shouldn’t treat this as needing to be compatible with MCP hosts that are compatible with MCPB. MCPB is an inspiration/template, like Umbrel or Start9, and there’s no need to maintain backward compatibility with it. That would indeed complicate our design unnecessarily, since CVM servers aren’t meant to be used by MCP hosts that follow the stdio spec, that’s a different use case. The use case we’re designing for is a way to bundle and distribute CVM servers so users can discover them and run them easily. Think of it as a one-click installation with a manifest for discoverability and ease of deployment.

That said, if you think following the shape proposed by the MCPB manifest is better or more elegant, we should do it. Personally, I don’t think we need to maintain backward compatibility with their enums and so on. We could use the meta field and the conventions we already have, as I think it’s a good way to handle custom fields or environment mappings defined by the servers. But I’d love to hear your thoughts.

As for keeping secrets out of plaintext configurations, I completely agree.

Please share your thoughts, and let’s keep shaping the design of this. Thanks for your work!

[abhayguptas]

Makes sense, I have already converted the PR to draft so nothing gets merged while we are still shaping the design.

I did some research to get a better foundation before suggesting anything. Looked at three things: how cvmi internally handles config and the serve/use flow, how MCP servers are actually built (both stdio and native CVM), and how Umbrel and Start9 handle their bundling and config injection. Sharing what I found and what I think based on that.

On not needing MCPB backward compatibility

Totally agree. After looking at it more carefully, MCPB is designed for a very different use case, local stdio servers installed into Claude Desktop. Our use case is distributing CVM servers that run over Nostr. Trying to stay compatible with their spec was adding constraints that don't help us. For example, their server type enum only allows node/python/binary/uv, their mcp_config assumes stdio, and there is no concept of transport or relay config. I think we should use their manifest shape as a reference where it makes sense but define our own format that fits our needs cleanly.

What I learned from Umbrel and Start9

Both use a similar pattern worth borrowing:

• The package declares what it needs (metadata, config schema, dependencies), the platform handles the how
• Secrets are never shipped in the bundle. They are auto-generated or prompted at install time and stored by the platform
• Config injection happens through environment variables. The platform resolves values and passes them to the process or container
• Docker is used as the execution engine for isolation and reproducibility, but images are referenced and pulled at runtime, never bundled

Start9 has a particularly interesting config system. They define a full typed config spec (with enums, ranges, validation rules, defaults, and a "masked" flag for sensitive fields), and the host auto-renders a settings UI from it. Something like that could be really nice for us down the line.

Suggestions for our design

Based on the research, here is what I think makes sense:

• Our own manifest format inspired by MCPB but not bound by it. We can define our own server types, transport modes, and config fields without worrying about breaking someone else's spec. The format stays a zip archive with a manifest.json inside, simple and portable.
• Transport field stays. The stdio vs cvm split maps directly to how cvmi already works. For stdio, the Gateway wraps the server and handles everything. For cvm, we inject config via env vars and let the server manage its own transport. This is clean and matches the existing architecture.
• Typed config spec for user facing settings (like Start9). Instead of just a flat user_config, we could have a proper schema that describes each setting with type, default, description, and a sensitive flag. cvmi serve could then prompt the user for required values on first run, auto-generate secrets, and store them securely outside the bundle.
• Secrets handled by the platform, not the bundle. Private keys, API keys, and anything sensitive should be resolved by cvmi at runtime. The manifest only declares what the server needs (like "this server needs a private key" or "this server needs an API key for service X"), cvmi handles prompting, generating, and storing them in .env or a local keystore.
• Docker support as a first class thing in our format. Since we are not bound by MCPB, we can properly define docker and compose support without hacks. The bundle references an image, cvmi pulls it on first serve, and runs it. For multi-container setups, a compose file in the bundle handles orchestration.
• A cvmi pack that validates and guides. The wizard should be smart about the transport mode. For stdio bundles, it just needs the basic manifest fields. For cvm bundles, it should ask about env mappings. For docker bundles, it asks for the image reference. The validation should be against our spec, not MCPB's.

What do you think? Happy to put together an updated design doc with the revised manifest schema and workflow once we align on the direction.

[harsh04044]

Agreed on dropping host compatibility, that takes care of my first point about cvm bundles not running in a standard MCPB host. The thing I'd separate from it though, since it changes your "should we follow the MCPB shape?" question: two things were getting bundled together:

1. host compatibility (can a generic MCPB host run our bundle), which we're dropping, and
2. format/tooling compatibility (does our manifest validate against MCPB's schema, so we can reuse mcpb pack/validate/sign).

What does the format side actually buy us? Mostly their pack/validate/sign CLI and a bit of familiarity. pack/validate is thin, and Abhay's cvmi pack already covers it (no mcpb dependency). The one that'd matter for a marketplace is sign/verify, but that's X.509, and it doesn't pull weight when we already have a signing identity in the server's pubkey (the same one users discover and connect to). So I'd go with Abhay's "own format, inspired by MCPB" too. Not because it's more elegant, but because the tooling we'd inherit doesn't earn the constraints.

There are a couple of things I'd want to nail down too, mainly how provenance works (the pubkey, not a new PKI) and how the manifest relates to the announcement servers already publish, so we're not maintaining the same metadata twice. We can get into those once we've aligned on direction and Abhay's design doc is up, no rush.

[ContextVM-org]

@abhayguptas I think we are on the right track, good suggestions. I think I just have a little nuance about

For stdio bundles, it just needs the basic manifest fields. For cvm bundles, it should ask about env mappings

I think that stdio servers could also need some envs right? So the distinction might be unnecessary, both stdio and cvm transports can define env mapping. Aside from that I agree with your other points and suggestions.

About @harsh04044 comments:

1. Shouldn't be a constraint for us, generic MCPB hosts don't need to be compatible
2. We can use their implementation as reference, but we should not have it as dependency. That will let us with a clean room and we can move forward with the specific features of our design.

About sign/verify, instead of X.509 certificates, we can use Nostr Schnorr signatures. The bundle author signs the manifest with their own Nostr keypair, and the signature is embedded directly in manifest.json. This is simpler, fully offline, and costs nothing.

How it could work

The signature lives in a _sig field inside the manifest:

{
  "manifest_version": "0.3",
  "name": "my-cvm-server",
  "version": "1.0.0",
  "_meta": {
    "com.contextvm": {
      "content_hash": "sha256:e3b0c44298fc1c14...",
      "transport": "cvm",
      "env_mapping": {
        "relays": "CVM_RELAYS",
        "encryption": "CVM_ENCRYPTION"
      }
    }
  },
  "_sig": {
    "pubkey": "abc123...",
    "id": "sha256 of canonical manifest (without _sig)",
    "signature": "86f25c...",
    "created_at": 1718123456
  }
}

_sig fields:

Field	Purpose
pubkey	Author's Nostr public key (hex)
id	SHA-256 of the canonical manifest JSON (with _sig removed, sorted keys, no whitespace)
signature	Schnorr signature of id using the author's nsec
created_at	Unix timestamp of when the signature was created

content_hash in _meta.com.contextvm is the SHA-256 of all bundle files (sorted by path). It's included in the manifest before signing, so the signature cryptographically binds both the manifest metadata and all bundle contents in one operation.

Signing flow

1. Compute content_hash = SHA-256(all bundle files in sorted order)
2. Insert content_hash into _meta.com.contextvm
3. Remove _sig from manifest (if present)
4. Canonicalize JSON (sorted keys, no whitespace)
5. id = SHA-256(canonical_manifest) — covers content_hash too
6. signature = schnorr_sign(id, author_nsec)
7. Insert _sig with pubkey, id, signature, created_at
8. Pack the ZIP

Verification flow

1. Extract ZIP
2. Verify content_hash matches actual bundle files
3. Remove _sig from manifest, canonicalize → SHA-256 → must equal _sig.id
4. schnorr_verify(_sig.id, _sig.signature, _sig.pubkey) must pass

All checks pass → valid. Any check fails → invalid. No trust levels, no Web of Trust, no relays — just a binary outcome. Everything works fully offline since Schnorr verification is a pure cryptographic operation.

The key insight is that the bundle author's Nostr identity is the root of trust — the same keypair can sign multiple servers, giving the author a stable identity across their catalog without any CA or certificate infrastructure.