Configuration reference

Generated from apps/gateway/src/config/ via mcpg config doc.
The audience-facing sections below are curated inside the generator; the per-block reference at the bottom is sourced from /// rustdoc + #[serde(...)] annotations on the live AppConfig tree.
Re-generate with: mcpg config doc > apps/gateway/docs/configuration.md.

Overview

Top-level gateway configuration. Loaded from YAML file and/or MCPG_ environment variables via figment. Bindings live under mcp.capabilities.{tools,prompts,resources,resource_templates}[]. Each binding carries an explicit nested backend: block that picks the implementation, discriminated by kind: (kind: http, kind: sql, kind: openai_chat, …). Env-var expansion (${env.X}) happens at startup time via CEL.

deny_unknown_fields is set so a typo at the root (or a stale renamed block left in an operator's YAML) fails parsing instead of silently parsing to defaults. The same strictness applies to every typed sub-config; this flag closes the gap at the root.

Operator workflow

The four config-tooling binaries cover the operator's full loop — pick a starting point, drill into a field, validate, boot:

$ mcpg config init                                    # pick a deployment template, write config.yaml
$ mcpg config explain governance.audit.on_failure    # describe a field by dotted path
$ mcpg config check config.yaml                       # pre-flight validate (multi-file too)
$ MCPG_CONFIG=config.yaml mcpg                        # boot

Multi-file layering is supported — files later on the command line override earlier ones, and MCPG_* env vars apply last:

$ MCPG_CONFIG=base.yaml:production-overrides.yaml mcpg

For in-place config rotation (kill -HUP) vs restart-required fields, see the config sources & hot-reload guide.

For IDE autocomplete, point your YAML language server at the committed schema:

# yaml-language-server: $schema=../../examples/deployments/config.schema.json
gateway:
  server:
    bind_address: "127.0.0.1:8787"
    # ↑ IDE autocompletes here, with `///` doc-comment as hover.

Top-level keys (Layout D'')

Layout D'' collapsed the pre-D'' flat root into seven typed top-level keys. The migration map for any pre-D'' YAML or env-var examples you might still be reading:

The ten D'' top-level keys are: mcp:, governance:, gateway:, observability:, feature_flags:, debug:, schema_registry:, storage:, cluster:, plugins: (plus MCPG_CONFIG-only config_source:). governance: and gateway: are umbrellas — their children correspond one-to-one to former root peers.

MCPG_* env vars track the new shape with __ as the dotted-path separator. The corresponding env-var prefix migrations:

Quick start (minimal viable)

Goal: gateway answers /health, tools/list, and one tools/call against your binding. No auth, no cluster, no compliance plumbing.

Template: dev-single-node (mcpg config init --template dev-single-node). Six fields are load-bearing — everything else takes a sensible default.

Boot it:

$ mcpg config init --template dev-single-node --output config.yaml
$ mcpg config check config.yaml
$ MCPG_CONFIG=config.yaml mcpg

Production hardening

Goal: external traffic, OIDC, audit you can ship to compliance, multi-replica behind an LB. Pick this once dev clicks.

Templates: production-single-redis (single instance), production-redis-cluster (multi-replica), production-nats-cluster (NATS variant) — all available via mcpg config init --template <name>.

Cluster pub/sub inheritance. Capability store:/bus: overrides default to kind: cluster (the cluster backend's primitive) when omitted, so when cluster.kind is redis or nats, mcp.configurations.delivery.bus and mcp.configurations.cancellation.bus automatically use the cluster's pub/sub. Server-initiated messages (cancellations, sampling responses, elicitations) reach the right replica without operator config. Override these only when you explicitly want single-replica behaviour despite a cluster (e.g. bus: { kind: memory }).

Advanced / experimental

Goal: pipeline tools, server-initiated suspensions, per-plugin observability carve-outs, control-plane attachment. Ignore until production basics are solid.

Multi-tenant deployments

MCPG has no top-level tenants: block by design. Per-tenant differentiation composes from three orthogonal primitives that already exist:

1. Tenant identity. Comes off the verified principal — identity.subject_id, identity.attributes.<claim>, identity.roles[], identity.groups[]. Whichever OIDC claim represents your tenant (commonly tid, org_id, or a custom claim) ends up under identity.attributes.<claim> once the inbound JWT verifier resolves it. No config knob is needed for the tenant ID itself.

2. Per-tenant binding allowlist. Goes through governance.policy.tool_access.rules[].cel_allow_if. Each binding gets a CEL predicate that references the principal's tenant claim:

   yamlCopy

   governance:
     policy:
       tool_access:
         default_minimum_trust: verified
         rules:
           - tool_name: "acme.*"
             cel_allow_if: 'identity.attributes.tenant == "acme" || "platform" in identity.groups'
           - tool_name: "partner.*"
             cel_allow_if: 'identity.attributes.tenant == "partner"'
           # shared.* falls through to default_minimum_trust (any verified caller).
   

   The CEL predicate runs pre-dispatch alongside trust-floor checks, so a deny is observable through the same audit shape (mcpg.policy.tool_call.denied) as any other policy denial.

3. Per-tenant rate limit + quota. Lives in the rate-limit plugin (rate limiting is plugin-only). The plugin's config is keyed by tenant identity from the same identity surface. Example shape (rate-limit plugin's config; the actual fields depend on the plugin you load):

   yamlCopy

   plugins:
     - id: dev.mcpg.builtin.rate_limit
       config:
         default:
           tools_per_minute: 1000
         by_tenant:
           acme: { tools_per_minute: 10000, burst: 200 }
           partner: { tools_per_minute: 100, burst: 10 }
         tenant_key: 'identity.attributes.tenant'
   

   Per-binding rate-limit references go through the backend's own per-use slot (point-of-use wiring) — same shape as any other plugin reference.

The pre-existing gateway.server.max_sessions_per_tenant knob is the one gateway-resident tenant-aware quota; it's enforced inside the session store (per-tenant cap on concurrent sessions) and works regardless of which CEL gate let the request through.

A first-class tenants: block that desugars into the above is a possible future addition. Until the recipes turn out painful in operator hands, the existing primitives stay the source of truth — adding a parallel mechanism would split tenant config across two places.

Templating and secret resolution

MCPG uses a single CEL-based expression syntax everywhere — ${...} outer markers wrap a CEL expression. There's exactly one form for environment variables, identity, arguments, OAuth tokens, and credential lookups; no parallel layers.

mcp:
  capabilities:
    tools:
      - name: github.user.repos.list
        description: Fetch a user's repositories from GitHub.
        backend:
          kind: http
          url: "https://api.github.com/users/${arguments.username}/repos"
          method: get
          headers:
            Authorization: "Bearer ${env.GITHUB_TOKEN}"
            X-Trace-Id: "${context.principal_id}-${arguments.username}"

gateway:
  plugin_registry:
    auth:
      username: "${env.GHCR_USERNAME}"
      password: "${env.GHCR_TOKEN}"

plugins:
  # Outbound OAuth 2.0 (RFC 6749 client_credentials) lives behind
  # the `dev.mcpg.credential.oauth-client-credentials` plugin.
  # Bindings reference issued tokens via the standard `cred://`
  # URI scheme — see the table below.
  - id: dev.mcpg.credential.oauth-client-credentials
    config:
      providers:
        analytics:
          token_url: "https://auth.example.com/oauth/token"
          client_id: "mcpg-prod"
          client_secret: "${env.ANALYTICS_CLIENT_SECRET}"
          scopes: ["read:events"]

Available roots:

env.X is resolved once at config-load — restarts pick up new values. Everything else is per-request, so a token rotation reaches in-flight calls on the next dispatch without a reload.

Reference

What follows is the full alphabetical reference of every type reachable from AppConfig, generated from /// rustdoc + #[serde(...)] annotations. Use mcpg config explain <field> to drill into a single field on the command line.

Top-level structure (AppConfig)

Every field on the root AppConfig, alphabetised. Click a type to jump to its per-block reference below.

Per-block reference

Every type reachable from AppConfig, alphabetised. Field tables show type, default, and the field's /// doc-comment summary.

AccessConfig

AdminAuthConfig

Variants:

• static_bearer

  • bearer_token_env: string

• trusted_header — Security: trusted-header mode requires a value match via trusted_value_env. Header-presence-only is insecure and generates warnings on every request.

  • header_name: string
  • trusted_value_env: string (optional)

• disabled

AdminConfig

Align

Horizontal cell alignment.

Allowed values:

• start
• center
• end

AppColumn

A table column bound to a JSON-path over each row.

AppCspDecl

Per-app author CSP declaration. Each axis is still intersected by the egress csp_policy; declaring an axis can only narrow, never widen.

AppDensity

Layout density.

Allowed values:

• comfortable
• compact

AppField

A detail/form field bound to a JSON-path.

AppProvidedTool

A read-only App-Provided Tool: surfaces client state to the agent.

AppRowAction

A per-row action: a tools/call with arguments mapped from the row.

AppTheme

Accent + density theming hints for the shell.

AppToolSource

The whitelisted read-only client state sources for App-Provided Tools.

Allowed values:

• selection
• visible_rows
• form_draft
• map_viewport

ApprovalsConfig

Tool-gate human approval configuration.

AppsConfig

apps: config — SEP-1865 MCP Apps support.

MCP Apps lets a server attach an interactive HTML UI to a tool. The ui/* postMessage protocol runs host↔iframe and never reaches the gateway; MCPG's role is passthrough of _meta.ui, capability advertisement (both downstream to clients and upstream to federated servers), federation resourceUri rewriting, and a tighten-only CSP/permission policy layer.

Off by default. When enabled: false, MCPG omits the io.modelcontextprotocol/ui extension from its capability advertisement and applies no policy — but _meta.ui still round-trips on tool/resource descriptors (passthrough is wire-shape, not capability-gated, so a client with a cached template keeps working). When enabled: true, advertisement lights up and the csp_policy / allowed_permissions / allowed_domains clamps below are enforced on egress.

AppsCspPolicy

The CSP-axis allow-lists. Defaults mirror a sensible middlebox posture: no bound on what the app may fetch/connect/redirect to (["*"]), but frame embedding and <base> pinned to self.

AppsPermission

A standard iframe permission. Serialized snake_case in config; maps to the camelCase _meta.ui.permissions key on the wire.

Allowed values:

• camera
• microphone
• geolocation
• clipboard_write

AuditConfig

Top-level audit: block. A top-level peer (rather than nested under observability:), with an inner schema aligned to the OTel signal-triad sinks-list pattern (logs / metrics / traces). Spec §9.12 defines the semantics; the fields here are the Rust projection.

Audit sinks fan out via sinks: [{kind, config, level?}]. The built-in dev.mcpg.builtin.audit.local-file activates only when its plugin id appears in sinks[].kind (there is no disable_builtins toggle — just omit the sink to disable it).

AuditOnFailure

Operator policy when an audit-sink emit fails.

Variants:

• fail_closed — (default) On emit failure, refuse to serve the triggering request. Compliance-safe: no action happens without a durable audit trail. Subtle: this can wedge the gateway if every registered sink is broken — operators should always configure at least one sink whose availability they actually monitor.

• fail_open — On emit failure, log + continue. The triggering request completes even if the audit event does not persist. Dev / CI use only — a compliance auditor will not accept this as SOC2-clean.

AuthConfig

How MCPG authenticates to the upstream.

AuthMode

Identity-propagation mode (RFC v1 §6).

Variants:

• none — No auth sent.

• service_token — Static bearer token.

• pass_through — Forward the inbound Authorization header verbatim.

• oauth_client_credentials — Machine-identity token via an OAuth provider.

• oauth_impersonation — Per-caller token-exchange (RFC 8693).

AuthorizationServerClientConfig

One OAuth client registered with the embedded authorization server.

AuthorizationServerConfig

Embedded EMA authorization server (governance.access.authorization_server).

BackendAnnotationsConfig

Tool annotation hints configurable per binding. Maps to MCP ToolAnnotations.

BackendConfig

BackendGovernanceConfig

BackendIconConfig

Configurable descriptor icon shape, mirrored onto MCP's Icon type.

BackendImpl

Implementation backend, identified by kind: with an opaque flattened spec. The gateway enumerates NO plugin kinds: a binding names a kind (a loaded BackendPlugin::kind() string) and every other key flattens into spec, forwarded verbatim to the plugin's register_profile / execute. The plugin owns and validates the schema; the gateway resolves kind against the registry at boot and fails closed on unknown / non-backend kinds. Mirrors WatchStrategyConfig::Plugin.

spec is an open object (no deny_unknown_fields); unknown keys are forwarded verbatim, so a spec-key typo is caught only by the owning plugin's register_profile (InvalidSpec at boot), not at config-load.

BackendQuotasRef

Per-binding quota reference — operator names at most one of each policy kind by id. The runtime gate that consults these refs is gated behind the governance-quotas cargo feature.

All three fields are independent options; an absent field means "no policy of that kind for this binding". A binding may name more than one kind at once (e.g. both a rate limit AND a concurrency cap), but at most one policy of each kind.

BackendResourceAnnotations

Operator-configurable MCP ContentAnnotations for a resource binding.

BudgetPolicy

One named budget policy (cost cap / call count / token count).

BusOverrideConfig

<capability>.bus: { kind, … } — produces an Arc<dyn mcpg_cluster_api::PubSub> at boot.

Recognised kind values: cluster, memory. (redis and nats are not accepted here — set cluster.kind: redis | nats and use kind: cluster here, or omit the override entirely.)

CancellationConfig

cancellation: config — cluster-wide cancellation fan-out (notifications/cancelled and tasks/cancel) plus a per-capability bus: override. Same shape as DeliveryConfig.

ChildInvokeConfig

Governance for the agentic child-dispatch surface (invoke_tool).

Direct tools/call always runs the full pre-dispatch stack; the child path an LLM binding drives did not. When enforce_gates is on, child invocations are routed through the same external policy_engine chain and tool_gate plugin chain as a direct call before reaching the backend, so tool-level access controls are not silently absent on the LLM-driven surface.

ClaimMappingConfig

ClientCertMode

Operator-facing client-cert acceptance mode.

Allowed values:

• none
• optional
• mandatory

CloudConfig

cloud: — present only on managed-fleet (mcpg.cloud) instances. Absent for self-host; every field defaults so a bare cloud: {} is inert.

CloudIsolation

Default isolation tier for the instance's placement.

Variants:

• shared — Shares a namespace pool with other tenants (default).

• dedicated — Dedicated nodes / namespace for the tenant.

CloudProvenance

Server-managed placement facts. Never trusted from a published config — the operator overwrites these at render time.

CloudTier

Billing tier the instance was provisioned under.

The variants mirror the licensing vocabulary (community | pro | team | enterprise) so this block and a license claim can be compared without a translation table. free is accepted as an alias for community, which is what this variant used to be called.

Variants:

• community

• unspecified — No tier asserted (self-host / unmanaged).

ClusterConfig

Top-level cluster config. The cluster plugin is the unified backbone for MCPG multi-instance state + coordination — it internally instantiates the four primitive impls (KeyValueStore, PubSub, Lease, Watch) and exposes them via accessor methods. kind is the discriminator; everything else is kind-specific config that flows straight to the plugin's factory as JSON.

yaml cluster: kind: redis # single_node | etcd | consul | nats | redis url: ${env.REDIS_URL} # rest of the fields are kind-specific key_prefix: "mcpg:cluster:"

kind: single_node (the default when cluster: is omitted) installs the in-process built-in coordinator and ignores the rest of the block. Other kinds map to mcpg-plugin-cluster-<kind>; the cdylib must still be declared under plugins[] (the inline cluster.* fields override any config: block on the matching entry).

ClusterReadinessGate

How coordinator health affects /ready.

Variants:

• off — Coordinator health never affects /ready (fail-open). Default.

• degrade — Surface a not-ready check in the readiness body when the coordinator is down, but keep the overall /ready status green.

• fail — /ready returns not-ready while the coordinator is unreachable.

ColumnFormat

How a cell value is rendered client-side.

Allowed values:

• text
• number
• currency
• date
• badge
• link

ConcurrencyPolicy

One named concurrency cap.

ConfigWatchConfig

gateway.config_watch: — operator-tunable file-watch reload trigger. Same semantics as SIGHUP and the admin endpoint: full GatewayRuntime rebuild via ArcSwap; session store preserved; credential cache rebuilt fresh; list_changed emitted per category for operational sessions on inventory delta.

ConflictPolicy

Conflict policy on a body-hash mismatch with a stored record. Today only Reject is implemented; permissive_replay is not offered.

Variants:

• reject — Same key + different body hash → JSON-RPC error -32010 IdempotencyConflict (HTTP 422).

ControlPlaneAttachConfig

Control Plane attachment config. See apps/gateway/src/runtime/cp/attach.rs for the wiring logic.

CredentialsClusterConfig

CredentialsConfig

Defaults are safe for single-node deploys; multi-instance deploys with per-caller dynamic credentials (e.g. Vault dynamic DB) MUST configure cluster.enabled: true to avoid cache divergence.

DebugCommandToolConfig

DebugConfig

Top-level debug: block — diagnostic tools surface only. The master switch lives at feature_flags.debug_tools_enabled. When that flag is false, every field below is ignored AND the mcpg.debug.* tools are stripped from the capability registry regardless of tools.exposure.

DebugNetworkToolConfig

DebugToolBackendsConfig

DebugToolExposureConfig

DebugToolsConfig

DeliveryConfig

delivery: config — delivery bus (the internal pub/sub that fans server-initiated messages out to the SSE stream owning each session) + per-capability bus: override. When bus is unset, the gateway inherits the cluster's pub_sub() primitive.

DisclosureLevel

Allowed values:

• summary
• redacted
• full

EnumSource

A dynamic-enum source: a sibling tool whose result supplies options.

FeatureFlagsConfig

Operator-controlled strictness / compat flags.

Every field defaults to the safe / standards-compliant value; flipping a flag is an explicit acknowledgement that the operator is taking on the risk the default protects against.

FederationCacheConfig

Capability-cache behaviour.

FederationConfig

One federated upstream MCP server.

FilterConfig

Allow/deny filtering of imported tool names (glob * suffix).

GatewayAppConfig

One gateway-authored templated app. Minted as ui://mcpg/<id>.

GatewayAppKind

The shipped shells a templated app can select.

Variants:

• table

• key_value — Dense label/value spec sheet (a compact detail).

• code_viewer — Read-only syntax-highlight-free code/text viewer.

• chart — Numeric series chart (bar/line) over the result columns.

• signature_pad — Canvas to draw a signature/sketch; submits a PNG data URL.

• audio_recorder — Record audio (microphone) and submit the clip.

• camera_capture — Capture a still photo (camera) and submit it.

• media_player — Play an audio/video asset referenced by the result.

• image_gallery — Browse a set of images from the result.

• file_upload — Select/drag files and submit their contents.

GatewayConfig

GovernanceConfig

Tool-call governance lifecycle: who → allowed? → extra gate → recorded → within limits.

Every child defaults to its own zero-value: an empty governance: block is valid YAML and produces a fully-default configuration (anonymous identity, untrusted-by-default policy, no human-gate signing key, audit channel disabled, no quotas declared).

HealthCheckConfig

HealthProbeConfig

Periodic health-probe configuration. The probe is the only writer of PluginState::Degraded; without it plugins stay perpetually Active regardless of whether they're actually responding.

IdempotencyConfig

idempotency: config — opt-in dedupe for tools/call and tasks/create. When enabled: false (the default), the gateway omits the dev.mcpg/idempotency extension from its initialize capability advertisement and silently ignores any _meta["dev.mcpg/idempotency-key"] the caller sets.

IdempotencyScopeKind

Default scope strategy for idempotency records. Operator can widen to per_tenant (service-account dedupe) or narrow to per_session (ephemeral test harnesses).

Note: global is intentionally NOT a variant — cross-tenant replay is a known anti-pattern, so we don't expose the footgun.

Variants:

• per_session — All requests sharing one MCP session share the namespace. Useful for ephemeral test harnesses; resets on every re-initialize.

• per_identity — All requests sharing one resolved identity (OIDC subject + auth provider) share the namespace. The default — matches Stripe / Square idempotency semantics.

• per_tenant — All requests sharing one tenant id share the namespace. Useful for service-to-service workloads where multiple service accounts retry the same operation.

ImportConfig

Which capability surfaces to import.

JwksConfig

KindRef

Discriminator + config payload at every consumer slot. Operators write { kind: <value>, ...config } in YAML; the gateway parses it as this type and resolves via [resolve_kind].

The config: field is a free-form JSON object passed to the resolved handle (built-in or plugin). The slot's resolver validates kind; the implementation validates config.

LicenseConfig

LogsConfig

observability.logs: — the logs signal.

Gateway internals (every tracing::info!() / warn!() / error!() call) AND plugin-emitted log events both flow through the configured sink list. Default sinks ship one stderr JSON emitter — production deployments add file, otlp, or plugin sinks (Loki, Splunk, …) by appending entries to sinks:.

MapAppConfig

Map binding for kind == map.

MapRenderMode

Map rendering mode.

Variants:

• plot — Coordinate plot on a canvas — zero network, no CSP delta.

• raster_tiles — Raster basemap tiles — needs tile_url + a CSP allowance.

McpCapabilitiesConfig

mcp.capabilities: — the MCP protocol-advertised surface.

Matches the protocol's initialize handshake's capabilities vocabulary: tools / prompts / resources / resource_templates, plus the gateway-side feature configs that govern protocol behaviour (tasks, elicitation, sampling, roots).

McpConfig

Top-level mcp: block — the MCP protocol surface.

Two children that mirror MCP's own vocabulary: - capabilities: — what the server advertises in the initialize handshake (tools, prompts, resources, resource_templates, tasks, elicitation, sampling, roots). - configurations: — runtime-emergent state handling (sessions, pipelines, subscriptions, delivery, cancellation). Operator only tunes persistence + constraints; the items themselves are created by clients at runtime.

McpConfigurationsConfig

mcp.configurations: — runtime-emergent state handling.

McpElicitationConfig

mcp.elicitation: — gateway behavior for server-initiated elicitation prompts. Today carries only timeout_ms; future per-elicitation-type config can grow here.

McpRegistryConfig

One MCP registry to auto-federate.

McpRootsConfig

mcp.roots: — gateway behavior for server-initiated roots-list requests forwarded to the client.

McpSamplingConfig

mcp.sampling: — gateway behavior for server-initiated sampling (LLM completion) requests forwarded to the client.

MetricsConfig

observability.metrics: — the metrics signal.

Gateway internals (every metrics::counter!() / gauge!() / histogram!()) flow through the configured sink list. The canonical Prometheus exporter is a plugin: operators wire kind: dev.mcpg.observability.prometheus. The sinks: [] list otherwise carries plugin ids (dev.acme.observability.datadog, etc.) — there are no built-in factory kinds for metrics.

NamingConfig

Prefixes applied to imported capability names / URIs.

NotificationFilterConfig

Scoping filter for resource change notifications. Determines which subscribers receive notifications/resources/updated when the watch engine detects a change.

Variants:

• (unnamed variant) — Fan-out to all subscribers (default, no filter).

• (unnamed variant) — Only notify subscribers whose principal_id matches the event's user context.

• (unnamed variant) — Only notify the originating session.

• (unnamed variant) — CEL expression evaluated per subscriber. Variables: subscriber.principal_id, subscriber.trust_level, subscriber.roles, subscriber.groups, subscriber.scopes, subscriber.attributes, event.uri.

  • expression: string
  • scope: string

OAuthResourceMetadataConfig

Configuration for the OAuth Protected Resource Metadata endpoint (RFC 9728).

ObservabilityConfig

Top-level observability: block — the OpenTelemetry signal triad (logs / metrics / traces) plus audit fan-out.

Each signal carries a sinks: [...] list of [SinkConfig] entries. Each entry's kind: field dispatches to either a built-in sink factory (stderr / stdout / file / otlp / prometheus) or a plugin id resolved against the gateway's plugin registry at boot.

Master switch. enabled: false (default true) silences every child regardless of their own enabled: flags — useful for embedded use cases where the host process owns observability or for minimal-footprint test runs. Each child also has its own enabled: for finer-grained control. The accessor helpers below (is_logs_on(), is_metrics_on(), is_traces_on(), is_audit_on()) implement the AND-fold so call sites can't forget either flag.

OidcOAuthConfig

OidcProviderConfig

OnDeprecated

Policy for deprecated servers.

Variants:

• serve_and_warn — Keep federating; log + count the deprecation.

• exclude — Drop the federation (clients see list_changed).

PipelinesConfig

pipelines: config — pipeline state store + per-capability store: override. When store is unset, the pipeline KV inherits from the cluster's key_value_store() primitive.

PluginEntryConfig

Configuration for a single plugin entry.

PluginFfiLimitsConfig

Per-plugin FFI hardening overrides for native cdylib plugins.

Native plugin calls are wrapped by the host in spawn_blocking + tokio::time::timeout and bounded RString returns. Defaults are the spec-level constants in mcpg_plugin_protocol::abi (FFI_{LIFECYCLE,CONTROL,DATA}_TIMEOUT_DEFAULT_MS, FFI_MAX_PAYLOAD_BYTES). Operators set per-plugin overrides here to widen the budget for a known-slow plugin (e.g. a backend that proxies an upstream multi-second API) or to tighten the cap on a plugin that has a stricter SLO.

None on any field means "inherit the spec default".

PluginHttpRouteConfig

Operator-side tuning for an http_route plugin entry. Every field is optional; the struct is omitted entirely for plugins that don't need any override.

PluginObservabilityToggle

Per-plugin observability toggle. Each signal is independent — operators can disable metrics for one plugin while leaving its logs and traces flowing. Events still route through the GLOBAL observability.{logs,metrics,traces}.sinks list when admitted; this struct only controls whether a plugin's events make it that far + at what level.

PluginRegistryAuthConfig

Registry authentication configuration. At most one source of credentials is consulted at push/pull time: an explicit username+password pair (or env-interpolated variants), otherwise the docker config.json at docker_config_path, otherwise anonymous.

PluginRegistryConfig

Configuration for resolving plugin artifacts from OCI registries. Covers default registry, local cache, auth, TLS, and signature policy.

This section is only consulted when at least one plugin entry has source.oci set. For purely local deployments (every plugin loaded from source.path), all defaults apply and the registry subsystem does nothing.

PluginRegistryMirrorConfig

A mirror registry entry. Mirrors are consulted in order before the reference's source registry, matching the common pull-through cache / air-gap deployment pattern.

PluginRegistryTlsConfig

TLS configuration for registry HTTPS connections.

PluginResourceLimitsConfig

Resource limits for Wasm plugins.

These limits constrain the sandbox resources available to a Wasm plugin. If not specified, system defaults are used (64 MiB memory, 10M fuel, 100ms timeout).

PluginSourceConfig

Plugin artifact source configuration.

Exactly one of path / oci must be set. Both unset is invalid; both set is invalid. The source type determines how the gateway resolves the artifact at boot time.

PolicyCacheConfig

Configuration for the policy decision cache (L1 process-local).

PolicyConfig

PromptArgumentConfig

QuotasConfig

governance.quotas: registry.

Three named-policy lists (rate_limits / budgets / concurrency) plus the storage backend that holds the runtime counters. Bindings opt into specific policies by id via their own per-binding quotas: block.

RateLimitPolicy

One named rate-limit policy.

RateLimitRate

RegistryAuthConfig

Consumer auth presented to the registry API.

RegistryAuthMode

Variants:

• none — Anonymous reads (the generic spec's default).

• bearer — Authorization: Bearer <token>.

• headers — Arbitrary static headers (API-key style sub-registries).

• cred — Bearer minted by a credential-issuer plugin (credential is a cred:// URI) under the gateway's machine identity.

RegistryDefaultsConfig

Defaults applied to every synthesized federation.

RegistryFilterConfig

Which registry servers are eligible.

RegistryOauthDiscoveryConfig

Sync-time OAuth discovery for registry servers.

RegistrySafetyConfig

Network posture for the registry endpoint.

RegistryServerOverride

Per-server override, keyed by registry server name.

RegistrySyncConfig

Sync cadence + bounds.

RegistryUpstreamSafetyConfig

Upstream network posture defaults for synthesized federations. Deliberately narrower than a hand-written federation's upstream_safety: the registry chooses which servers exist, so the dangerous knobs are not registry-reachable.

RequestStateConfig

request_state: config — the MRTR requestState codec used by the modern wire's suspending tools/call arm to encrypt pipeline-resumption blobs.

Inert until a modern client connects. Lives under mcp.configurations because the codec manages runtime-emergent resumption state alongside sessions / pipelines / subscriptions / delivery / cancellation / idempotency — operator tunes the encryption key, the runtime mints + serves the rest.

yaml mcp: configurations: request_state: # 32-byte ChaCha20-Poly1305 key, base64-encoded. # Generate via: head -c 32 /dev/urandom | base64 encryption_key: "<base64-32-byte-secret>"

Absent the key the gateway mints an ephemeral one at boot (with a WARN log) — pending resumptions issued before a gateway restart become undecodable after restart.

ResourceWatchConfig

Per-binding resource watch configuration. Defines how changes to a resource are detected for notifications/resources/updated.

ResponseCacheConfig

Operator-facing config for the gateway-managed LLM response cache. The cache backs BackendHost::cache_get / cache_put; chat + embedding bindings opt in per-binding via their own cache.enabled: true knob, the cache only exists at all if this config is non-disabled.

kind: in_process is the default — content-addressed BLAKE3 LRU cache with 64 MiB byte cap, lost on restart. kind: disabled turns the cache off gateway-wide; per-binding cache.enabled becomes a no-op.

Variants:

• (unnamed variant)

  • kind: string
  • max_bytes: integer

• (unnamed variant)

ResponseConfig

Per-call response limits.

RetryConfig

Per-binding retry configuration. Only applies to HTTP, gRPC, GraphQL, NATS, and Kafka bindings.

SchemaEntry

A named schema entry in the registry. Exactly one source must be provided.

ServedRegistryConfig

mcp.registry: — serve a v0.1 MCP-Registry view of this gateway. The catalog exposed is exactly one server entry: the gateway itself (its whole governed surface hangs off one MCP endpoint), so pointing a registry-driven client policy here yields "the approved server is MCPG".

ServerConfig

SessionConfig

Upstream-session behaviour.

SessionsConfig

sessions: config — session lifecycle store + per-capability store: override. When store is unset, the session KV inherits from the cluster's key_value_store() primitive; when set, the override pins to an in-process backend (memory / file).

SignalToggle

Per-plugin per-signal toggle. Four knobs:

• enabled (default true): when false, every event from this plugin's crate is dropped at the bridge before it reaches the sink fan-out — the "silence this noisy plugin" pattern. - level (logs / traces only): minimum severity an event must clear to be emitted. Composed into the bridge layer's permissive filter so per-plugin verbosity boosts AND suppressions both work. Accepted: trace / debug / info / warn / error (case-insensitive). - mode (default inherit): how to route events that pass the gate. inherit flows through the global sink list (the default behaviour). replace routes ONLY to the plugins listed under sinks — used for compliance carve-outs ("audit logs go to my SIEM, never to stdout"). tee fans out to BOTH the global sink list AND the per-plugin sinks. - sinks: plugin ids of the sink plugins to use under mode: replace | tee. Each id MUST match a registered sink plugin for the corresponding signal — log sink for logs.sinks, metrics sink for metrics.sinks, span sink for traces.sinks. If any id is unknown to the matching signal, the gateway refuses to boot (validated post-registration in app::validate_per_plugin_sink_ids). Listing a real log sink id under metrics.sinks is rejected — sink-kind crossover is a typo, not a feature.

SignatureConfig

Per-plugin signature configuration.

Consolidates three signature concerns into one per-plugin block: - The content-hash pin. - The verification policy — per-plugin overridable, with the global default in gateway.plugin_registry.default_signature_policy:. - The Ed25519 trusted keys this artifact must verify against — per-plugin so plugins from different vendors can carry different keys without pooling them in one trust anchor.

SignaturePolicy

Signature verification policy for native plugin artefacts. The Ed25519 signature attached to the artefact (<artifact>.sig or the packaged plugin.sig) is the primary check; this policy governs behaviour when the signature is missing or invalid. Set per-plugin via plugins[*].signature.policy:, or as a gateway-wide default via gateway.plugin_registry.default_signature_policy:.

Variants:

• disabled — Signature checks are skipped entirely. Development only; gateway emits a governance.plugin.signature_policy_disabled audit event for any entry that resolves to this policy so the choice is visible in the compliance trail.

• warn — Log a warning for missing or invalid signatures but proceed with the load. Default — safe for first rollout.

• enforce — Refuse to load any artefact whose signature is missing or does not verify against the configured trusted keys. Recommended for production.

SinkConfig

One sink in an observability signal's sinks: [...] list. The kind: field dispatches to a built-in factory (stderr, stdout, file, otlp, prometheus) or to a plugin id (any other value is looked up in the plugin registry at boot).

config: is the sink-kind-specific config object. Built-in kinds validate their own config: shape at boot; for plugin sinks, the plugin's own config schema applies.

level: is an optional per-sink severity floor. When None, the sink inherits the signal's level:. Useful for stderr: warn, file: debug setups where the console is quiet but a file captures everything. Per-sink level overrides are parsed but not yet enforced; today signal-level level: is the only enforced floor.

SinkMode

How to route events for a per-plugin signal toggle. Operator schema: mode: inherit | replace | tee.

Variants:

• inherit — Inherit the global sink list — the same routing every other plugin's events use. Default.

• replace — Route admitted events ONLY to the per-plugin sinks list. Skips the global sink fan-out entirely. Used for compliance carve-outs (audit logs stay inside the SIEM).

• tee — Tee — admitted events flow to BOTH the global sink list AND the per-plugin sinks list. Useful when an operator wants to keep default routing but additionally mirror a noisy plugin's events to a debugging sink.

StorageConfig

Top-level storage: block. Holds the gateway's content-store providers + the LLM response cache.

StorageProviderConfig

One operator-declared content-store provider, an entry in storage.providers: [...]. The kind field selects the storage plugin (in_process / file_system / s3 / future plugins); config is the per-plugin configuration object whose schema is owned by the plugin (see each plugin's plugin.yaml).

StoreOverrideConfig

<capability>.store: { kind, … } — produces an Arc<dyn mcpg_cluster_api::KeyValueStore> at boot.

Recognised kind values: cluster, memory, file. (redis and nats are not accepted here — set cluster.kind: redis | nats and use kind: cluster here, or omit the override entirely.)

SubscriptionsConfig

subscriptions: config (resource subscriptions) — subscription store + per-capability store: override + per-session quota. When store is unset, the subscription KV inherits from the cluster's key_value_store() primitive.

SynthesizeConfig

Change-notification synthesis: when the upstream has no server→client push channel, the gateway can manufacture notifications/resources/updated for subscribed federated resources by polling them through the normal read path and hash-diffing the content (the watch engine's poll strategy). list_changed synthesis rides the existing capability TTL refresh (cache.capability_ttl_secs) and needs no knob here.

SynthesizeMode

Gate on synthesized change notifications.

Variants:

• auto — Synthesize only when the upstream demonstrably cannot push resource updates: the modern (2026-07-28) wire and the stdio transport. A legacy streamable-http upstream keeps its GET-SSE push path and is not polled.

• poll — Always poll, even for upstreams with a push channel (covers legacy servers that only emit resources/updated for subscriptions the gateway does not place upstream).

• off — Never synthesize.

TaggedVariableCompletionSource

Variants:

• (unnamed variant) — Static list of completion values. Same shape as the shorthand bare-list but with explicit kind tag.

  • kind: string
  • values: array<string>

• (unnamed variant) — Dynamic dispatch: at completion time, the gateway calls [crate::backends::CapabilityRegistry::complete_argument], which routes to the named backend's BackendPlugin::complete_template_variable(binding_name, variable_name, prefix, &config). The backend returns up to 100 completions matching the prefix.

  • backend: string
  • config: any
  • kind: string

TasksConfig

tasks: config (MCP 2025-11-25 tasks system) — task store + per-capability store: override + retention tuning. When store is unset, the task KV inherits from the cluster's key_value_store() primitive. Tuning fields (default_ttl_ms, reaper_interval_ms, max_tasks_per_session, result_wait_ms) are orthogonal and apply to whichever backend resolves.

TlsConfig

TLS configuration for the HTTP transport.

TokenSourceConfig

TokenSourceKind

Allowed values:

• authorization_bearer
• custom_header

ToolAccessPolicyConfig

ToolTrustRuleConfig

TracesConfig

observability.traces: — the traces signal.

Span lifecycle events (every tracing::info_span!() / debug_span!() and every plugin-emitted span) flow through the configured sink list. The canonical sink is otlp (exports to an OpenTelemetry Collector). Default: traces disabled (operators opt in by setting enabled: true and adding sinks).

TransportMode

Transport mode determines whether MCPG runs as an HTTP server or a stdio JSON-RPC process.

Allowed values:

• http
• stdio

TrustLevelConfig

Allowed values:

• unauthenticated
• header_asserted
• verified

TrustedIdpConfig

One enterprise IdP trusted to issue ID-JAGs.

TrustedKeyConfig

One trusted-key entry inside SignatureConfig.trusted_keys.

TunnelConfig

Reverse-tunnel egress config. The gateway dials out to a relay and answers tunnelled MCP traffic through its own request path.

TunnelExposure

Whether a tunnel gets a public hostname.

Allowed values:

• public
• private

TunnelFederationConfig

Reverse-federation ingress config. A tunnel://<name>/<path> federation upstream resolves through the relay's federation ingress to <relay_ingress_url>/federate/<name>/<path>. This gateway authenticates its ORG to the relay with the token field below (carried in the X-MCPG-Tunnel-Token header, which the relay consumes and never forwards); the end-user's Authorization bearer flows through, untouched, to the tunnelled gateway as the MCP caller identity.

TunnelTrustMode