Install MCPG

The ways to run the MCPG gateway — Docker image, Helm chart, install.sh, the npm or PyPI package, 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 (Windows as a .zip). Install with the install.sh script (curl … | sh — Linux glibc/musl and macOS), the model-context-protocol-gateway package on npm or PyPI, or the cosign-signed OCI images below. There is no Homebrew tap.

With cargo. cargo install model-context-protocol-gateway --version 0.1.0-beta.72 installs a small launcher for the same four commands: the first run downloads the release binaries for your platform and checks them against the SHA-256 sums published in the crate. cargo binstall with the same arguments installs the release binaries directly. Until the first stable release, cargo needs --version: it does not choose a prerelease by itself.

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.72 —
# 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/charts/mcpg-operator --version <chart-version> -n mcpg \
  --set image.tag=0.1.0-beta.70 \
  --set rbac.create=true \
  --set webhook.enabled=true

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

Each chart release defaults to the images released with it: the operator chart runs the operator release it was cut with, and gives every MCPGGateway without spec.image.tag the gateway release it was cut with. To hold an image back, pin it: image.tag on the operator chart, and spec.image.tag on each MCPGGateway (for example 0.1.0-beta.72, no leading v).

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/charts/mcpg --version <chart-version> -n mcpg \
  --set replicaCount=3 \
  --set nats.enabled=true

Always pass --version. The charts are prereleases (0.1.0-beta.N), and each chart versions on its own, so the operator chart and the gateway chart have different numbers. Without --version, Helm skips every prerelease, finds no chart and stops; --devel takes the newest chart instead of the one you pinned. Each chart's package page lists its versions: mcpg, mcpg-operator, mcpg-control-plane.

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.
# https://github.com/mcpg-dev/mcpg/releases lists every release.
TAG=v0.1.0-beta.72
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 five public CLIs. Each one releases from its project's own repository, with its own version. install.sh fetches all five by default, each at its newest release; --bin <binary> narrows it to one. For a manual install, grab <binary>-<version>-<triple>.tar.xz from the releases page in the table and put the binary anywhere on PATH.

Binary	What it is	Releases
`mcpg`	The gateway itself	mcpg-dev/mcpg
`mcpg-config`	Scaffold, validate and explain config (`mcpg config <sub>`)	mcpg-dev/mcpg-config
`mcpg-inspector-tui`	The terminal UI of the inspector	mcpg-dev/mcpg-inspector
`mcpg-plugin`	Build, sign and publish plugins	mcpg-dev/mcpg-plugin
`mcpg-cloud`	Talk to mcpg.cloud	mcpg-dev/mcpg-cloud

The inspector's releases carry only its terminal UI, mcpg-inspector-tui. The full mcpg-inspector binary — web UI, terminal UI and CLI verbs, which mcpg inspector and mcpg --inspector run — ships as the image ghcr.io/mcpg-dev/mcpg-inspector, or builds from source.

The self-hosted control plane server (mcpg-control-plane) is not part of this suite: its release archives ship from a licensed repository, so install.sh --bin mcpg-control-plane needs access to that repository. Its image (ghcr.io/mcpg-dev/mcpg-control-plane-server) and its Helm chart are public.

The model-context-protocol-gateway package, on npm and on PyPI, carries mcpg, mcpg-config, mcpg-cloud and mcpg-plugin, plus a model-context-protocol-gateway command that runs mcpg. On npm the binary for your platform arrives as an optional dependency, so an install with --omit=optional does not work:

bash

npm install -g model-context-protocol-gateway
npx model-context-protocol-gateway --help    # one-shot, nothing installed globally

On PyPI each platform has its own wheel:

bash

pipx install model-context-protocol-gateway
uvx model-context-protocol-gateway --help    # one-shot, nothing installed

On Alpine Linux the binaries need libgcc (apk add libgcc). There is no Homebrew tap.

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.