MCP Orchestrator — Helm Chart

Current release: v2.4.x family (latest: v2.4.12) — Helm chart on magertron.com/charts.

Install guide for the MCP Orchestrator Helm chart, focused on on-prem and private-cloud Kubernetes deployments. If you're on a managed cloud (EKS / GKE / AKS), the chart works there too — see the last appendix.

New in v2.4.x: Service account lifecycle (create, rotate, revoke, expiry reminders), audit log with configurable retention, owner-email identity linking, HMAC-SHA256-signed webhooks. See Service Account Lifecycle below.

---

Quickstart

The fastest path to a working install is the bundled script. It does everything below (preflight, license setup, node labeling, helm install, post-install verification) with one command:

git clone https://github.com/magertron/orchestrator.git
cd orchestrator
./install.sh --license /path/to/your-license.json

The script supports both fresh installs and upgrade-in-place. Pass --mode reinstall for a destructive fresh start (it requires typing 'destroy' to confirm); the default --mode upgrade preserves data.

The rest of this README walks through the same install manually — use it to understand exactly what the script is doing, or when your environment needs custom values the script doesn't expose.

---

Installing the CLI

mcpctl is the command-line client. It talks to a running orchestrator over HTTPS to deploy MCP servers, manage users and service accounts, and inspect cluster state. The CLI is Apache 2.0 licensed and free for all customers.

Pick your platform:

# Homebrew (macOS or Linux)
brew install magertron/tap/mcpctl

# curl one-liner (macOS or Linux)
curl -fsSL https://magertron.com/install-mcpctl.sh | sh

# Debian / Ubuntu (one-time setup, then apt install)
curl -fsSL https://magertron.com/apt/magertron-archive-keyring.gpg \
    | sudo tee /etc/apt/trusted.gpg.d/magertron-archive-keyring.gpg > /dev/null
echo "deb [signed-by=/etc/apt/trusted.gpg.d/magertron-archive-keyring.gpg] https://magertron.com/apt stable main" \
    | sudo tee /etc/apt/sources.list.d/magertron.list
sudo apt update && sudo apt install mcpctl

# RHEL / Fedora / Rocky
sudo curl -fsSL https://magertron.com/yum/magertron.repo -o /etc/yum.repos.d/magertron.repo
sudo dnf install mcpctl

Full CLI usage guide: see mcpctl/README.md.

---

What you're installing

The chart deploys the full MCP Orchestrator platform to your cluster:

• Orchestrator (2 replicas by default) — the control plane, REST API, and admin UI
• Envoy gateway — TLS termination and HTTP routing to MCP servers
• PostgreSQL (×2) — one in-cluster database for orchestrator identity & audit, one for the mcp-inventory service that tracks deployed servers, service accounts, and grants
• mcp-sync sidecar — watches MCP server CRDs and pushes Envoy routes
• mcp-inventory — durable store for service accounts, orgs, and per-SA lifecycle state (expiry, rotation, last-used, owner email)
• Namespaces for MCP servers (mcp-prod, mcp-staging, mcp-dev)
• Network policies isolating MCP server namespaces
• RBAC — a ServiceAccount + ClusterRole granting the orchestrator the k8s permissions it needs to deploy MCP servers on your behalf
• CRDs — the mcp.io/McpRoute custom resource used internally

After install you retrieve the auto-generated admin password from the Kubernetes Secret (instructions printed in the post-install notes), log in, change the password, optionally apply an Enterprise license, and start deploying MCP servers.

---

Prerequisites

You need these BEFORE running helm install. The chart can auto-generate TLS certificates, JWT keys, and the database/admin passwords for you (the default behavior, suitable for dev/PoC), but for production deployments we recommend providing your own — see the relevant prerequisite sections below and the pr