Configure the gateway

The gateway reads one validated AppConfig YAML file. How to scaffold it from a template, understand its top-level blocks, inject secrets safely, validate before boot, and reload without downtime.

Everything the gateway does — which tools it serves, who may call them, what gets audited, where telemetry goes — comes from one AppConfig YAML file. This page is the task-oriented tour of authoring that file. For the exhaustive, schema-generated key list, see the Configuration reference; for the tooling flags, the mcpg config reference.

Start from a template, not a blank file

Don't hand-write the config. Scaffold a validated one from a deployment template, then edit:

bash

mcpg config init --template dev-single-node --output config.yaml
mcpg config check config.yaml   # exits 0 + "valid" when the config boots

mcpg config init --list shows every template: dev-single-node, production-single-redis, production-redis-cluster, production-nats-cluster, air-gapped, and multi-tenant. Each one is a real, bootable config for its shape — pick the one closest to your target and trim from there.

The top-level blocks

An AppConfig is a handful of top-level keys. You rarely set all of them:

Block	What it configures
`gateway`	The HTTP listener — `bind_address`, `mcp_path`, `health_path`, allowed origins, the binding health prober.
`mcp`	The served surface: `capabilities.tools[]`, `resources[]`, `prompts[]`, each with a nested `backend:`.
`cluster`	How replicas share state — `kind: single_node` (default) or a coordinator (`redis`, `nats`, `consul`, `etcd`).
`governance`	Access, policy, approvals, and the `audit` ledger — the governance lifecycle.
`observability`	Logs, metrics, and traces — the signal triad.
`plugins`	The plugin set: ids, sources (`oci:` / path), trust mode, and granted capabilities.
`credentials`	Named secret material the config references through `cred://` handles.

The gateway rejects unknown fields at boot (deny_unknown_fields), so a typo or a stale key fails fast rather than being silently ignored. That is why mcpg config check catches most mistakes before you ever start the process.

Inject secrets without baking them in

Never write a token or password literally into the config. Two substitution forms resolve at config-load, from trusted config-origin positions only:

${env.VAR} — pulled from the process environment when the config is loaded. Use it for tokens passed by your orchestrator or secret manager.
cred://<name> — a handle into the credentials: block, which itself sources material from env, files, or a secret-store plugin.

yaml

mcp:
  capabilities:
    tools:
      - name: github.list_repos
        backend:
          kind: http
          url: "https://api.github.com/user/repos"
          headers:
            Authorization: "Bearer ${env.GITHUB_TOKEN}"

Both forms are resolved only from config-authored positions — a caller can never smuggle a cred:// or ${env.…} string through a tool argument and have it expanded. Audit what a config will resolve before shipping it:

bash

mcpg config secrets --json config.yaml    # every secret reference, machine-readable

Validate, explain, and inspect

mcpg config is more than a linter — it is how you understand a config you inherited:

bash

mcpg config check base.yaml prod-overrides.yaml   # layered validate (CI / pre-commit)
mcpg config explain governance.audit.on_failure   # type, default, enum, and doc for one key
mcpg config wiring config.yaml                     # which kind: each consumer slot resolves to
mcpg config schema > config.schema.json            # JSON Schema for IDE autocomplete

Point your editor at the emitted schema for inline completion and validation:

yaml

# yaml-language-server: $schema=./config.schema.json

Layer base + overrides

check and the runtime loader both accept multiple files that merge left-to-right, so you keep one base config and thin per-environment overlays:

bash

MCPG_CONFIG="base.yaml:prod-eu.yaml" mcpg

The gateway reads its config path(s) from MCPG_CONFIG. MCPG_* environment variables can also override individual keys at boot — mcpg config wiring folds those in so you see the effective result.

Reload without downtime

You do not have to restart to change config. When a control plane is attached, a re-published config is pushed to the running gateway and applied in place — the listener stays up and existing sessions are unaffected. Under the Kubernetes operator, editing an MCPGGateway's spec.config re-renders the ConfigMap and rolls the Deployment.

Where to go next

Configuration reference — every key, generated from the live schema.
Backends reference — the 32 backend plugins a tool binding can select.
Protocol versions — the mcp: block and wire negotiation.
Governance model — the governance block, end to end.