Install MCPG

The real ways to run the MCPG gateway — Docker image, Helm chart, install.sh, Homebrew, a prebuilt release tarball, or build from source.

There are four ways to get the gateway running. Pick based on where you're deploying:

Path	Best for
Docker image	Local runs, single-node, CI
Helm chart	Kubernetes — HA fleets, the operator
Release tarball	Bare metal / VMs without containers
Build from source	Contributors, custom builds

Platform support. Every release ships prebuilt binaries for x86_64 and aarch64 Linux (glibc and musl), Apple Silicon, and x86_64 Windows. Install with the install.sh script (curl … | sh — Linux glibc/musl and macOS), the Homebrew tap, or the cosign-signed OCI images below; the user CLIs additionally ship an x86_64 Windows .zip.

Note. There is no cargo install mcpg. The gateway and plugin crates are publish = false, so they're not on crates.io. Use one of the paths below.

Docker image

The gateway publishes to GitHub Container Registry on every release:

bash

docker pull ghcr.io/mcpg-dev/source-code/gateway:latest
# or pin a version:
docker pull ghcr.io/mcpg-dev/source-code/gateway:v1.0.0-rc.17

The image runs as a non-root user, ships a signed (cosign keyless) manifest, and expects a config file at /etc/mcpg/config.yaml. Mount your config and the default listener is on :8787:

bash

docker run --rm \
  -p 8787:8787 \
  -v "$(pwd)/config.yaml:/etc/mcpg/config.yaml:ro" \
  ghcr.io/mcpg-dev/source-code/gateway:latest

# verify it's up
curl http://127.0.0.1:8787/health

The image already sets MCPG_CONFIG=/etc/mcpg/config.yaml and binds to 0.0.0.0:8787. To generate a starter config, see the quickstart.

Helm chart (Kubernetes)

For Kubernetes, install the operator first, then declare gateways as MCPGGateway custom resources. The operator reconciles each one into a Deployment, Service, ConfigMap, and ServiceAccount.

bash

kubectl create namespace mcpg

# 1. The operator (watches MCPGGateway + 7 other CRDs cluster-wide)
helm install mcpg-operator oci://ghcr.io/mcpg-dev/source-code/charts/mcpg-operator --version 0.1.0 -n mcpg \
  --set rbac.create=true \
  --set webhook.enabled=true

The operator exposes metrics and health on :8443 and its admission webhook on :9443.

You can also install a gateway directly with the mcpg chart (NATS or Redis as an optional chart dependency for multi-instance state):

bash

helm install gw oci://ghcr.io/mcpg-dev/source-code/charts/mcpg --version 0.1.0 -n mcpg \
  --set replicaCount=3 \
  --set nats.enabled=true

For the full HA walk-through — operator, autoscaling, plugin sets, and cluster state backends — see the Kubernetes install guide.

Release tarball (bare metal / VMs)

Each GitHub Release ships a self-contained tarball for every target triple — each containing the mcpg binary plus the bundled plugin cdylibs, with a sha256 checksum. The install.sh script (curl -fsSL … | sh) auto-detects your OS, architecture, and libc and fetches the matching one; the manual steps below pin a single triple, so swap it for yours.

bash

VERSION=v1.0.0-rc.17
BASE=https://github.com/mcpg-dev/source-code/releases/download/$VERSION

curl -fsSLO "$BASE/mcpg-${VERSION}-x86_64-unknown-linux-gnu.tar.xz"
curl -fsSLO "$BASE/mcpg-${VERSION}-x86_64-unknown-linux-gnu.tar.xz.sha256"

sha256sum -c "mcpg-${VERSION}-x86_64-unknown-linux-gnu.tar.xz.sha256"
tar -xf "mcpg-${VERSION}-x86_64-unknown-linux-gnu.tar.xz"

# place mcpg on PATH
sudo install -m 0755 mcpg /usr/local/bin/mcpg
mcpg --version

The config tooling (mcpg config <sub>) lives in a companion binary that ships as its own artifact under the same release — install.sh fetches it automatically alongside mcpg; for manual installs grab mcpg-config-${VERSION}-<triple>.tar.xz from the same release and place mcpg-config next to mcpg (or anywhere on PATH).

Boot it with a config file via the MCPG_CONFIG environment variable — see the quickstart.

Build from source

You need a recent Rust toolchain and the workspace's package manager (pnpm). The repo is an Nx monorepo, so build through nx:

bash

git clone https://github.com/mcpg-dev/source-code.git
cd source-code

# build the gateway binary (release)
pnpm nx run mcpg:build --configuration=production

# the binary lands in the workspace target dir; run it directly:
cargo run -q -p mcpg --bin mcpg

Two helper binaries ship in the same crate and are useful immediately:

bash

# scaffold a validated starter config from a template
cargo run -q -p mcpg --bin mcpg-config -- init --list

# validate any config before booting
cargo run -q -p mcpg --bin mcpg-config -- check config.yaml

Next steps

Quickstart — generate a config, validate it, and boot in under five minutes.
Configuration reference — every config key, generated from the live schema.
Kubernetes install guide — production HA on Kubernetes.