mcpg — the gateway (and the hub CLI)

← CLI reference

mcpg is the gateway server. Configuration comes from the MCPG_CONFIG env var (a path or path-separator-joined list of files) and/or the repeatable --config flag — the two layer together, later wins. See Configuration below.

Composition flags — attaching to / embedding a control plane

The rule across the CLI family: flags shape the gateway; subcommands run or operate everything else. The three flags conflict with each other (and --enroll errors against an explicit gateway.control_plane in config — config wins).

• --enroll <URL> runs the agent in-process (the cp-attached build feature, on in release binaries) and enrolls. The agent gRPC endpoint defaults to the enrollment URL's host on :7844; --cp-grpc <URL> overrides. The pairing persists in MCPG_STATE_DIR (gateway-pairing.json + gateway-agent/ creds), so subsequent plain mcpg runs re-attach with the same instance identity — no re-enrollment.
• --control-plane / --cp boots the CP in-process with mcpg cp serve --dev semantics (sqlite in the state dir, auth_mode=none) and auto-enrolls this gateway over loopback: one command, and the console at http://127.0.0.1:7843 already shows the gateway online. Deliberately not sticky — the CP only exists inside --cp runs. It shares the state-dir database with mcpg cp serve --dev, so graduating to split processes keeps all data. (Requires the embedded-cp build feature, on in release binaries.)
• --no-cp detaches for one run.

Configuration (MCPG_CONFIG + --config)

Config comes from two ordered inputs that layer together, later wins: the MCPG_CONFIG env var (files only) and the repeatable --config flag.

MCPG_CONFIG is a single path or a path-separator-joined overlay list of files:

MCPG_CONFIG=config.yaml                  mcpg          # single file
MCPG_CONFIG=base.yaml:production.yaml     mcpg         # Unix overlay (':' separator)
MCPG_CONFIG="base.yaml;prod.yaml"         mcpg         # Windows overlay (';')

--config <source> adds layers after the MCPG_CONFIG files (repeat it; later wins). Unlike MCPG_CONFIG, a --config source is not path-split, so it can be more than a file path:

mcpg --config base.yaml --config prod.yaml            # two files, prod wins
mcpg --config https://cfg.example.com/gateway.yaml    # fetched at boot (https)
mcpg --config base64:Z2F0ZXdheToge30K                 # inline base64 YAML
mcpg --config 'data:application/yaml;base64,Z2F0…'    # RFC 2397 data URI

Remote and inline (https/base64/data) layers are held in memory and captured at boot — they are never written to disk, and a hot-reload reuses the boot snapshot rather than re-fetching. Only file layers hot-reload. Put secrets behind ${env.X} / cred:// references regardless of source.

Merge order: struct defaults → each YAML layer in order (MCPG_CONFIG files, then --config sources) → MCPG_* env vars last. Env overrides use __ (double underscore) as the nested-key separator; MCPG_CONFIG itself is the file entry point and is never treated as an override:

# Override gateway.server.bind_address without editing the file
MCPG_CONFIG=config.yaml MCPG_GATEWAY__SERVER__BIND_ADDRESS=0.0.0.0:8080 mcpg

Each __ segment maps to one level of nesting, so the env var name mirrors the YAML path (gateway.server.bind_address → MCPG_GATEWAY__SERVER__BIND_ADDRESS).

Transport modes are http (default, Axum HTTP/SSE on gateway.server.bind_address, default 127.0.0.1:8787) and stdio (JSON-RPC over stdin/stdout).

mcpg dev — local plugin loop

Each --plugin <path> adds one plugin to the running gateway by path (no OCI, no packaging). The descriptor (plugin.yaml) is read from next to the artifact (or the crate root for target/release/…).

mcpg plugin new --kind tool_gate --name my-gate        # scaffold (delegates to mcpg-plugin)
cd mcpg-plugin-tool-gate-my-gate && cargo build --release
mcpg dev --plugin target/release/libmcpg_plugin_tool_gate_my_gate.so
# Iterate against an MCP client over stdio:
mcpg dev --plugin ./libfoo.so --plugin ./libbar.so --stdio

Examples

MCPG_CONFIG=config.yaml mcpg                            # run the gateway (HTTP :8787)
MCPG_CONFIG=config.yaml mcpg --stdio                   # stdio transport
mcpg plugin list ./target/release                      # delegate to mcpg-plugin

Where does the config come from in production? On Kubernetes the operator sets MCPG_CONFIG from MCPGGateway.spec.config; standalone, you author it with the config tooling.