The MCPB Bundle Format: Packaging MCP Servers for Distribution

MCPB (MCP Bundle) is the standardized packaging format for distributing MCP servers. If you’ve ever published an npm package, pushed a Docker image, or distributed a Python wheel, the concept is familiar: take your code, its dependencies, and the metadata needed to run it, then package everything into a single distributable artifact. MCPB does this for MCP servers, with additional structure for runtime configuration, capability declarations, and security metadata that general-purpose package managers don’t provide.

Every server on mpak.dev is a MCPB bundle. Every MCP server NimbleBrain builds on client engagements ships as a MCPB bundle. The format is what makes one-command installation, automated security scanning, and standardized runtime configuration possible.

The Problem MCPB Solves

MCP servers are distributed as source code. Clone a repository, read the README, install the dependencies, figure out the start command, set the environment variables, and hope everything works. This process has three failure modes that compound as you scale.

Dependency conflicts. Your MCP server needs httpx 0.25. Your existing environment has httpx 0.24. Your other MCP server needs httpx 0.26. Traditional installation means resolving these conflicts manually, creating virtual environments, or hoping the version ranges are compatible. At five to ten servers per deployment, dependency management becomes a full-time job.

Configuration guesswork. How do you start the server? Is it python server.py or python -m mypackage.server? What environment variables does it need? What are the valid values? The README might cover the happy path. It probably doesn’t cover the edge cases your environment creates. You end up reading source code to answer questions that should be declared metadata.

The “it works on my machine” problem. A server that runs perfectly in the author’s development environment fails on your system. Different Python version. Missing system library. Implicit dependency on a tool that happens to be installed on the author’s machine. Without standardized packaging, every installation is a configuration debugging session.

MCPB eliminates all three. Dependencies are vendored, so there is no install-time resolution. Configuration is declared, so there is no guessing. The bundle is self-contained, so there are no environment-specific failures.

Bundle Anatomy

A MCPB bundle is a directory with a defined structure, packaged into a distributable artifact. Here is what lives inside.

manifest.json: Identity and Metadata

The manifest is the bundle’s identity card. It tells the registry (and anyone evaluating the server) what this package is, who built it, and what it does.

{
  "name": "salesforce-mcp",
  "version": "1.2.0",
  "description": "MCP server for Salesforce CRM: contacts, opportunities, accounts, and pipeline analytics",
  "author": "NimbleBrain <engineering@nimblebrain.ai>",
  "license": "MIT",
  "keywords": ["salesforce", "crm", "contacts", "opportunities"],
  "mcp_version": "1.0"
}

name follows naming conventions: lowercase, hyphens for separators, descriptive of the target system. version is semantic: major.minor.patch. mcp_version declares which MCP protocol version the server implements, so clients can check compatibility before installation.

The manifest is what makes the registry searchable. When someone runs mpak search crm, the registry matches against names, descriptions, and keywords from manifest files. Structured metadata replaces guessing.

mcpb.json: Runtime Configuration

This is the file that makes one-command execution possible. It declares exactly how to start the server, what arguments to pass, and what environment variables it expects.

{
  "mcp_config": {
    "command": "python",
    "args": ["-m", "salesforce_mcp.server"],
    "env": {
      "SALESFORCE_INSTANCE_URL": {
        "description": "Your Salesforce instance URL",
        "required": true
      },
      "SALESFORCE_ACCESS_TOKEN": {
        "description": "OAuth access token for Salesforce API",
        "required": true
      }
    }
  },
  "permissions": {
    "network": ["*.salesforce.com"],
    "filesystem": "none"
  }
}

When you run mpak run salesforce-mcp, the runtime reads this file and knows exactly what to execute. No guessing at the start command. No searching the README for environment variable names. The bundle declares its own execution contract.

The permissions block is critical for security evaluation. It declares the network endpoints the server connects to and the filesystem access it requires. The MCP Trust Framework uses these declarations to verify that the server’s actual behavior matches its stated scope. A server that declares network: ["*.salesforce.com"] but makes requests to undeclared endpoints at runtime gets flagged.

Server Code

The actual MCP server implementation. Python, TypeScript, Go: the language doesn’t matter to the bundle format. The mcp_config in mcpb.json abstracts the language-specific invocation. Users install and run the bundle; the runtime handles execution details.

Vendored Dependencies

This is where MCPB diverges most from traditional package distribution. Dependencies are resolved at pack time and included in the bundle. When you install a MCPB bundle, there is no install-time dependency resolution. No calls to PyPI or npm. No version conflict with your existing environment. The bundle ships with everything it needs.

For Python servers, vendored dependencies live in a deps/ directory. mpak automatically sets PYTHONPATH=deps/ at runtime, so the server finds its dependencies without polluting the system Python environment. For Node servers, node_modules/ is included in the bundle. The isolation is built into the format.

This approach trades disk space for reliability. A MCPB bundle is larger than a manifest-only package because it includes its dependency tree. The tradeoff is worth it: installation never fails due to dependency resolution, and the server runs identically on every machine that installs the bundle.

Python Conventions

Python MCP servers use module execution, which handles relative imports correctly and avoids the common pitfalls of running Python scripts directly.

The mcpb.json mcp_config for a Python server:

{
  "mcp_config": {
    "command": "python",
    "args": ["-m", "package_name.server"]
  }
}

The server entry point needs the standard module guard:

if __name__ == "__main__":
    mcp.run()

mpak sets PYTHONPATH=deps/ automatically, so vendored dependencies resolve without additional configuration. The server runs in its own dependency context without interfering with the system Python or other servers.

This convention exists because of a real problem. Running python server.py directly breaks relative imports in package-structured servers. Module execution (python -m package_name.server) resolves the package hierarchy correctly. Every Python server NimbleBrain has built follows this convention. Adopting it avoids the most common class of “works in development, breaks in production” errors.

TypeScript Conventions

TypeScript (Node) servers point the manifest at the compiled entry file:

{
  "mcp_config": {
    "command": "node",
    "args": ["${__dirname}/dist/index.js"]
  }
}

The ${__dirname} variable resolves to the bundle’s installation directory at runtime. The compiled JavaScript lives in dist/, and node_modules/ is vendored in the bundle. No npm install at install time. No npx indirection. Direct execution of the compiled output.

TypeScript servers must compile before packing. The bundle includes the compiled JavaScript, not the TypeScript source. Source maps are optional but recommended for debugging. The development workflow is: write TypeScript, compile, pack the output, publish.

The Stdout Rule

One convention that catches every first-time MCP server author: stdout must be clean JSON-RPC only. MCP communication happens over stdio. The client sends JSON-RPC messages to the server’s stdin, and the server responds on stdout. Any non-JSON-RPC output on stdout (log messages, startup banners, debug prints, library warnings) corrupts the protocol stream and breaks the connection.

All logging, diagnostic output, and informational messages go to stderr. This is enforced in the MCPB validation step. If your server prints anything to stdout that isn’t a valid JSON-RPC message, mpak validate flags it and the bundle won’t pass registry requirements.

This is the single most common reason a working MCP server fails as a published bundle. The fix is straightforward: configure your logging framework to write to stderr, remove print statements, and ensure no dependency writes to stdout during initialization.

Capabilities Declaration

Beyond permissions, a MCPB bundle can declare its MCP capabilities: the tools it exposes, the resources it provides, and the prompts it offers. These declarations are optional but strongly recommended; they power the registry’s capability search and feed into the trust evaluation.

{
  "capabilities": {
    "tools": [
      "create_contact",
      "search_deals",
      "update_opportunity",
      "get_pipeline_metrics"
    ],
    "resources": [
      "salesforce://contacts",
      "salesforce://opportunities"
    ]
  }
}

Declared capabilities serve two audiences. For users, they answer “what can this server do?” before installation. For the MTF scanner, they establish the expected behavior baseline. A server that declares four tools but exposes eight at runtime has undeclared capabilities, which may be benign (the author forgot to update the declaration) or concerning (the extra tools weren’t meant to be visible). Either way, the discrepancy is flagged.

Creating a Bundle from an Existing Server

You have an MCP server. It works locally. You want to distribute it. Here’s the path.

Add a manifest.json with the required metadata: name, version, description, author, license. Add a mcpb.json with the runtime configuration: command, args, environment variables. Declare permissions and capabilities.

Run mcpb pack. The tool resolves and vendors dependencies, validates the manifest and mcpb.json, checks the stdout rule, and produces the distributable bundle. If validation fails, the tool reports exactly what needs fixing: missing required fields, stdout pollution, unresolvable dependencies.

The packing process takes minutes for a simple server. The metadata files take the longest to write, and most of that is thinking about what to declare, not typing. For teams that build multiple servers, the manifest and mcpb.json become boilerplate: copy from an existing bundle and update the specifics.

Why Not Docker

Docker images solve a similar problem: packaging an application with its dependencies into a portable artifact. The difference is scope and purpose.

A Docker image packages an entire operating system layer, runtime, and application. It’s designed for general-purpose application deployment. A MCPB bundle packages a single MCP server with its direct dependencies. It’s designed for MCP-specific distribution and runtime management.

Docker images don’t carry MCP-specific metadata. They don’t declare tools, resources, or permissions. They don’t integrate with trust scoring frameworks. They don’t support one-command search and discovery through a protocol-specific registry. You could distribute MCP servers as Docker images, and some teams do, but you lose the metadata, security scanning, and developer experience that MCPB provides.

MCPB bundles are lighter, faster to install, and purpose-built. For teams already running MCP infrastructure through mpak, MCPB is the right format. For teams that want container isolation, nothing stops you from running a MCPB bundle inside a container. The formats are complementary, not competing.

The Distribution Standard

The MCPB format is open. The specification is published on GitHub. Any tool, registry, or platform can produce and consume MCPB bundles. mpak is the primary registry, but the format isn’t locked to mpak. Organizations running private registries use the same format. CI/CD pipelines that build MCP servers produce MCPB bundles as artifacts.

This is Business-as-Code at the packaging layer. The server’s identity, configuration, permissions, and capabilities are structured data, not tribal knowledge buried in README files and Slack threads. A MCPB bundle is a complete, machine-readable description of an MCP server that any tool can consume. The packaging standard becomes the distribution standard becomes the security scanning standard. One format, end to end.

For a step-by-step guide to creating and publishing your first bundle, see Publishing to mpak. For the trust framework that evaluates every published bundle, see MCP Trust Framework In Detail.