mcpg-ctl (control plane)
The MCPG control-plane CLI — run the CP locally, enrol gateways, sign in via OIDC, and drive Cloud provisioning + cluster admin.
mcpg-ctl runs and drives the control plane. It is a solo-dev / operator
tool: it can run the CP server in-process, enrol a local gateway agent, sign in
via OIDC, and drive Cloud provisioning + cluster admin against the CP's /v1
REST API. (It does not do org / workspace / plugin-set CRUD or config
export / apply — that's the CP REST API and the operator CRDs.)
Global flags: --state-dir <path> (env MCPG_STATE_DIR, default ~/.mcpg)
and --json-logs (env MCPG_JSON_LOGS). State (the SQLite DB and credentials)
lives under the state dir.
What it talks to: the CP REST API (default http://127.0.0.1:7843, flag
--cp-url / env MCPG_CP_URL) and CP gRPC (default :7844). Auth to the REST
API is a session cookie (--session-cookie / env MCPG_SESSION_COOKIE,
injected as mcpg_sid); for loopback CPs running auth_mode=none no cookie is
needed. login is full OIDC PKCE.
Run / inspect the CP
| Command | Purpose | Key flags |
|---|---|---|
quickstart | Run the CP with Tier-0 defaults and open the UI | --bind-http 127.0.0.1:7843, --bind-grpc 127.0.0.1:7844, --no-browser |
serve | Run the CP with explicit options (no browser) | --bind-http, --bind-grpc |
status | Show what's running locally + DB stats | — |
doctor | Diagnostics — port / state-dir / browser availability | — |
mcpg-ctl quickstart # 30-second wedge → opens the UI
mcpg-ctl serve --bind-http 0.0.0.0:7843 # headless
mcpg-ctl status
Enrol a local gateway agent
| Command | Purpose | Key flags |
|---|---|---|
gateway | Run a gateway agent that registers + heartbeats to the CP over gRPC | --enrollment-url <url> (env MCPG_ENROLLMENT_URL, first run), --cp-grpc http://127.0.0.1:7844, --instance-uid <uid> (env MCPG_INSTANCE_UID) |
gateway-status | Print stored agent state (creds, last CP endpoint, LKG config hash, registration time) | — |
mcpg-ctl gateway --enrollment-url "http://127.0.0.1:7843/enroll/abc123" # first run
mcpg-ctl gateway # later runs reuse cached creds
mcpg-ctl gateway-status
Federation sign-in
| Command | Purpose | Key flags |
|---|---|---|
login | OIDC PKCE sign-in; persists tokens + license to <state>/credentials.json | --issuer <url> (required, env MCPG_FED_ISSUER), --client-id mcpg-ctl, --no-browser |
logout | Clear stored credentials | — |
mcpg-ctl login --issuer https://auth.mcpg.dev
mcpg-ctl login --issuer https://auth.mcpg.dev --no-browser # SSH / headless
provision — managed (Cloud) gateways
Group flags: --cp-url, --session-cookie. create / delete stream an SSE
phase ladder (allocating → applying → ready) to stdout.
| Command | Purpose | Key flags |
|---|---|---|
provision create | Provision a managed gateway | --org, --workspace, --env, --name (all required); --image-tag latest, --replicas 1, --region, --isolation-tier, --custom-hostname |
provision delete | Tear down a gateway by instance UID | --org, --workspace, --env, --instance-uid (all required) |
provision history | List recent provisioning operations for an org | --org (required), --verbose |
mcpg-ctl provision create \
--cp-url https://cp.mcpg.dev --session-cookie "$MCPG_SID" \
--org acme --workspace prod --env us \
--name edge-1 --image-tag v1.0.0 --replicas 2 --region us-east-1
mcpg-ctl provision history --org acme --verbose
mcpg-ctl provision delete --org acme --workspace prod --env us --instance-uid edge-1-9f3c2a
cluster — managed K8s fleet admin
Group flags: --cp-url, --session-cookie. Reads /v1/clusters and hits the
admin API for register / decommission.
| Command | Purpose | Key flags |
|---|---|---|
cluster list | List managed clusters + capacity | — |
cluster health | Fleet-wide health summary | — |
cluster register | Register a cluster (admin-only) | --name, --region, --gateways-max (required); --isolation-tier shared, --cpu-millicores-total, --memory-bytes-total |
cluster decommission | Take a cluster out of the allocator pool | --id (required), --force (override drain protection — orphans running gateways) |
mcpg-ctl cluster list --cp-url https://cp.mcpg.dev --session-cookie "$MCPG_SID"
mcpg-ctl cluster register --name us-east-shared-1 --region us-east-1 --gateways-max 50
mcpg-ctl cluster decommission --id 7f2e1a90-… --force
The CP server mcpg-ctl talks to is documented at
mcpg-control-plane-server.