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

# <version> is a release tag without the leading `v`, e.g. 0.1.0-beta.21 —
# https://github.com/mcpg-dev/mcpg/releases lists them.
docker pull ghcr.io/mcpg-dev/mcpg:<version>

Every version is a multi-arch index; :<version>-amd64 and :<version>-arm64 are published alongside it for callers that pin one architecture. There is no :latest — nothing has graduated to a stable release yet, so a floating tag would point at nothing.

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/mcpg:<version>

# 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

# The tag carries a leading `v`; the asset filenames do not.
TAG=v0.1.0-beta.20
VERSION=${TAG#v}
BASE=https://github.com/mcpg-dev/mcpg/releases/download/$TAG

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 rest of the suite

mcpg is one of six binaries, each released as its own artifact under the same tag. install.sh fetches all of them by default; --bin <name> narrows it to one. For manual installs, grab <name>-${VERSION}-<triple>.tar.xz from the same release and put it anywhere on PATH.

Binary	What it is
`mcpg`	The gateway itself
`mcpg-config`	Scaffold, validate and explain config (`mcpg config <sub>`)
`mcpg-inspector`	Inspect and debug any MCP server — web UI, TUI, CLI
`mcpg-plugin`	Build, sign and publish plugins
`mcpg-cloud`	Talk to mcpg.cloud
`mcpg-control-plane`	The self-hosted control plane server

The same six ship as npm and PyPI distributions — npm i -g @mcpg-dev/mcpg installs every one as a bin, and pip install mcpg-cli does the same as console entry points — plus a Homebrew tap:

bash

brew tap mcpg-dev/mcpg https://github.com/mcpg-dev/mcpg
brew install mcpg mcpg-inspector

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

Build from source

You need a recent Rust toolchain:

bash

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

# build the gateway binary (release)
cargo build --release

# or run it directly:
cargo run -q

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.