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: cargo run -p mcpg --bin 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 hot-reload.md.

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'' (P1–P12) 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: examples/deployments/dev-single-node.yaml. 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.yaml (single instance), production-redis-cluster.yaml (multi-replica), production-nats-cluster.yaml (NATS variant).

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 (post-P0-3, 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 future option logged in docs/internal/FUTURE.md. 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: "${$identity.subject_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

ApprovalsConfig

Tool-gate human approval (RFC 0017) 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. See apps/gateway/docs/multi-version/mcp-apps-rfc.md.

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 four CSP-axis allow-lists. Defaults mirror a sensible middlebox posture: no bound on what the app may fetch/connect 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. Phase 2.

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

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

Variants:

• (unnamed variant)

  • expected_status_codes: array<integer>
  • headers: map<string, string>
  • kind: string
  • max_response_bytes: integer
  • method: HttpBackendMethod
  • require_json_response: boolean
  • timeout_ms: integer
  • url: string

• (unnamed variant)

  • args: array<string>
  • command: string
  • kind: string
  • max_output_bytes: integer
  • require_json_stdout: boolean
  • timeout_ms: integer

• (unnamed variant)

  • credentials_path: string (optional)
  • kind: string
  • max_response_bytes: integer
  • subject: string
  • timeout_ms: integer
  • url: string

• (unnamed variant)

  • headers: map<string, string>
  • kind: string
  • max_response_bytes: integer
  • method: string
  • service: string
  • timeout_ms: integer
  • url: string

• (unnamed variant)

  • headers: map<string, string>
  • kind: string
  • max_response_bytes: integer
  • operation: string
  • timeout_ms: integer
  • url: string

• (unnamed variant)

  • bootstrap_servers: string
  • group_id: string
  • kind: string
  • max_response_bytes: integer
  • request_topic: string
  • response_topic: string
  • timeout_ms: integer

• (unnamed variant)

  • delay_ms: integer
  • error: boolean
  • error_message: string (optional)
  • kind: string
  • passthrough: boolean
  • response: any

• (unnamed variant)

  • kind: string
  • pipeline_timeout_ms: integer
  • steps: array<PipelineStepConfig>

• (unnamed variant) — OpenAPI binding (mcpg-plugin-backend-openapi, kind openapi). References one operation of a source registered in the plugin's own config (plugins.entries[].config.sources). The plugin derives the tool input/output schema from the operation and dispatches the call as an outbound HTTP request — the operator names only which source + operation to surface, not a URL or schema.

  • kind: string
  • operation: string
  • source: string

• (unnamed variant) — SQL database binding (Postgres / MySQL / SQLite).

• (unnamed variant) — OpenAI public chat-completion API (mcpg-plugin-backend-llm-openai, kind openai_chat). Same flatten-passthrough pattern as Sql: the gateway forwards the raw spec to the plugin, which owns the schema. See docs/rfcs-archive/mcpg/mcp_gateway_llm_phase_5_rfc.md §5.0.

• (unnamed variant) — Azure OpenAI deployments (mcpg-plugin-backend-llm-openai, kind azure_openai_chat). Operator supplies a per-deployment URL with embedded ?api-version=….

• (unnamed variant) — Anthropic Messages API (mcpg-plugin-backend-llm-anthropic, kind anthropic_chat).

• (unnamed variant) — Google Gemini AI Studio API (mcpg-plugin-backend-llm-gemini, kind gemini_chat).

• (unnamed variant) — Generic OpenAI-compatible endpoint (mcpg-plugin-backend-llm-compat, kind compat_chat): vLLM, LocalAI, Together, Groq, OpenRouter, llama.cpp's OpenAI server, Vertex AI's OpenAI compatibility surface, etc. Operator MUST declare base_url; api_key is optional.

• (unnamed variant) — OpenAI embeddings API (mcpg-plugin-backend-llm-openai, kind openai_embedding).

• (unnamed variant) — Azure OpenAI embeddings deployments (mcpg-plugin-backend-llm-openai, kind azure_openai_embedding).

• (unnamed variant) — Google Gemini AI Studio embeddings (mcpg-plugin-backend-llm-gemini, kind gemini_embedding).

• (unnamed variant) — Generic OpenAI-compatible embeddings endpoint (mcpg-plugin-backend-llm-compat, kind compat_embedding).

• (unnamed variant) — OpenAI image generation (DALL-E) (mcpg-plugin-backend-llm-openai, kind openai_image).

• (unnamed variant) — Azure OpenAI image deployments (mcpg-plugin-backend-llm-openai, kind azure_openai_image).

• (unnamed variant) — Google Imagen image generation (mcpg-plugin-backend-llm-gemini, kind gemini_image).

• (unnamed variant) — Stability AI Stable Image generation (Core / SD3 / Ultra) (mcpg-plugin-backend-llm-stability, kind stability_image).

• (unnamed variant) — OpenAI text-to-speech (mcpg-plugin-backend-llm-openai, kind openai_tts).

• (unnamed variant) — Azure OpenAI TTS (mcpg-plugin-backend-llm-openai, kind azure_openai_tts).

• (unnamed variant) — OpenAI speech-to-text (Whisper) (mcpg-plugin-backend-llm-openai, kind openai_stt).

• (unnamed variant) — Azure OpenAI STT (mcpg-plugin-backend-llm-openai, kind azure_openai_stt).

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.

ClaimMappingConfig

ClientCertMode

Operator-facing client-cert acceptance mode. Same vocabulary as RFC 0008 §4.4.

Allowed values:

• none
• optional
• mandatory

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.entries[] (the inline cluster.* fields override any config: block on the matching entry).

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 — design doc §7 explicitly rejected permissive_replay for v1.

Variants:

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

ControlPlaneAttachConfig

Control Plane attachment config. See apps/gateway/src/cp_attach.rs for the wiring logic.

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

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).

GatewayConfig

GatherInputConfig

One entry in a [PipelineGatherStepConfig]. A trimmed projection of the standalone suspending-step configs carrying only the fields needed to mint the outgoing server request.

Variants:

• (unnamed variant)

  • correlation_token: string
  • kind: string
  • message: string
  • requested_schema: any

• (unnamed variant)

  • correlation_token: string
  • kind: string
  • max_tokens: integer
  • messages: array<SamplingMessageConfig>
  • system_prompt: string (optional)

• (unnamed variant)

  • correlation_token: string
  • kind: string

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.

HttpBackendMethod

Allowed values:

• post
• get

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 — see design doc §2.6. Cross-tenant replay is the #2 anti-pattern in the industry survey; 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.

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:.

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.

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

PipelineElicitationMode

Elicitation mode per MCP 2025-11-25. form collects a schema-driven response; url redirects the client to a URL and correlates the completion via notifications/elicitation/complete.

Allowed values:

• form
• url

PipelineSqlTxNestedStep

One SQL statement inside a sql_tx container. Mirrors the shape of a standalone binding's query block but scoped to the container's transaction.

PipelineStepConfig

Variants:

• (unnamed variant)

  • expected_status_codes: array<integer>
  • headers: map<string, string>
  • id: string
  • input_transform: string (optional)
  • kind: string
  • max_response_bytes: integer
  • method: HttpBackendMethod
  • require_json_response: boolean
  • timeout_ms: integer
  • url: string

• (unnamed variant)

  • args: array<string>
  • command: string
  • id: string
  • input_transform: string (optional)
  • kind: string
  • max_output_bytes: integer
  • require_json_stdout: boolean
  • timeout_ms: integer

• (unnamed variant)

  • credentials_path: string (optional)
  • id: string
  • input_transform: string (optional)
  • kind: string
  • max_response_bytes: integer
  • subject: string
  • timeout_ms: integer
  • url: string

• (unnamed variant)

  • bootstrap_servers: string
  • group_id: string
  • id: string
  • input_transform: string (optional)
  • kind: string
  • max_response_bytes: integer
  • request_topic: string
  • response_topic: string
  • timeout_ms: integer

• (unnamed variant)

  • headers: map<string, string>
  • id: string
  • input_transform: string (optional)
  • kind: string
  • max_response_bytes: integer
  • method: string
  • service: string
  • timeout_ms: integer
  • url: string

• (unnamed variant)

  • headers: map<string, string>
  • id: string
  • input_transform: string (optional)
  • kind: string
  • max_response_bytes: integer
  • operation: string
  • timeout_ms: integer
  • url: string

• (unnamed variant)

  • delay_ms: integer
  • error: boolean
  • error_message: string (optional)
  • id: string
  • kind: string
  • passthrough: boolean
  • response: any

• (unnamed variant)

  • expression: string
  • id: string
  • kind: string

• (unnamed variant) — Reshape the pipeline context by invoking a named transform plugin (RFC 0020). Generic bridge — works with any transform plugin; the first user is dev.mcpg.transform.jsonata. The plugin receives the full pipeline context (steps, arguments, context, tool_name) and its config (e.g. a JSONata expression); its output is the step result.

  • config: any
  • id: string
  • kind: string
  • plugin: string

• (unnamed variant)

  • error_message: string (optional)
  • expression: string
  • id: string
  • kind: string

• (unnamed variant)

  • correlation_token: string (optional)
  • elicitation_id: string (optional)
  • id: string
  • kind: string
  • message: string
  • meta: any
  • mode: PipelineElicitationMode
  • presentation_hint: string (optional)
  • requested_schema: any
  • skip_if_unsupported: boolean
  • timeout_ms: integer
  • url: string (optional)

• (unnamed variant)

  • correlation_token: string (optional)
  • id: string
  • include_context: SamplingIncludeContext (optional)
  • kind: string
  • max_tokens: integer
  • messages: array<SamplingMessageConfig>
  • meta: any
  • metadata: any
  • model_preferences: any
  • skip_if_unsupported: boolean
  • stop_sequences: array<string> (optional)
  • system_prompt: string (optional)
  • temperature: number (optional)
  • timeout_ms: integer
  • tool_choice: any
  • tools: array<any> (optional)

• (unnamed variant) — Pipeline step that sends roots/list to the client and suspends until the client responds with its root URIs. The result is stored in the pipeline context as steps.<id>.output.roots.

  • correlation_token: string (optional)
  • id: string
  • kind: string
  • skip_if_unsupported: boolean
  • timeout_ms: integer

• (unnamed variant) — SEP-2322 multi-entry MRTR. Emits several server-to-client input requests (elicitation / sampling / roots) in ONE suspension and resumes once the client answers them together. Distinct from listing the individual suspending steps in sequence (which suspends/resumes one at a time).

  • id: string
  • inputs: array<GatherInputConfig>
  • kind: string

• (unnamed variant) — Emit a notifications/message on the session's SSE channel. Non-suspending — pipeline continues immediately.

  • data: any
  • id: string
  • kind: string
  • level: string
  • logger: string (optional)

• (unnamed variant) — Emit a notifications/progress on the session's SSE channel. Non-suspending. Skipped (silently) when the inbound request didn't include a progressToken.

  • id: string
  • kind: string
  • message: string (optional)
  • progress: number
  • total: number (optional)

• (unnamed variant) — Nested SQL container with transactional semantics. Each inner step runs against a pinned connection; any error rolls the whole group back.

  • backend: string
  • id: string
  • input_transform: string (optional)
  • kind: string
  • steps: array<PipelineSqlTxNestedStep>

• (unnamed variant) — Fire-and-wait step. References an existing SQL binding whose profile declares [bindings.sql.await]. The plugin's inline await runtime is invoked: trigger query → poll-loop the check query → CEL predicate evaluation → matched row or timeout. Same machinery as the standalone SQL await binding, exposed for pipeline composability.

  • backend: string
  • id: string
  • input_transform: string (optional)
  • kind: string

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 (RFC 0018).

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.

PluginIntegrityConfig

Plugin artifact integrity verification.

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 per docs/rfcs-archive/mcpg/mcp_gateway_oci_plugin_registry_rfc.md.

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

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.

SamplingIncludeContext

Sampling context-inclusion hint. MCP defines exactly three variants; any other value on the wire fails deserialization so a misspelled config cannot silently degrade to the default.

Controls which MCP server context the client should include when fulfilling a sampling/createMessage request. Serialized as camelCase on the wire ("none", "thisServer", "allServers").

Allowed values:

• none
• thisServer
• allServers

SamplingMessageConfig

SchemaEntry

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

ServerConfig

SessionConfig

Upstream-session behaviour.

SessionMode

Upstream-session allocation strategy.

Variants:

• per_client — One satellite session per MCPG client session (Phase 1; D5).

• shared — One shared upstream session for all clients. Not yet supported.

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 (was integrity.sha256). - 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.

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

TrustedKeyConfig

One trusted-key entry inside SignatureConfig.trusted_keys.

UpstreamConfig

Upstream connection details.

UpstreamSafetyConfig

SSRF / DNS-rebinding posture for the upstream URL. Mirrors the HTTP binding's guard (runtime/safe_dns.rs).

UpstreamTransport

Upstream wire transport.

Variants:

• streamable_http — MCP Streamable HTTP (POST + SSE). Phase 1.

• stdio — Local stdio child process. Phase 4.

• legacy_sse — Legacy HTTP+SSE transport. Phase 4.

VariableCompletionSource

Per-template-variable completion source.

The bare-list shorthand stays valid (post-launch shipping shape): variable_completions: { region: ["us-east-1", "us-west-2"] } is read by the BareList arm and treated as if the operator had written { kind: static, values: [...] }. The tagged form is the new shape — kind: dynamic introduces backend dispatch.

Type: array<string> | TaggedVariableCompletionSource

VerificationConfig

Variants:

• (unnamed variant)

  • allow_hmac: boolean
  • allowed_algs: array<string>
  • kind: string
  • max_staleness_ms: integer
  • refresh_interval_secs: integer
  • timeout_ms: integer

• (unnamed variant)

  • client_id: string
  • client_secret_ref: string
  • introspection_url: string
  • kind: string
  • timeout_ms: integer

• (unnamed variant)

  • allow_hmac: boolean
  • allowed_algs: array<string>
  • client_id: string
  • client_secret_ref: string
  • introspection_timeout_ms: integer
  • introspection_url: string
  • kind: string
  • max_staleness_ms: integer
  • refresh_interval_secs: integer
  • timeout_ms: integer

WatchStrategyConfig

Variants:

• poll — Poll the resource periodically and compare SHA-256 hash.

  • interval_ms: integer

• nats_topic — Subscribe to a NATS subject — any message means the resource changed.

  • subject: string

• kafka_topic — Subscribe to a Kafka topic — any message means the resource changed.

  • group_id: string
  • topic: string

• webhook — Receive webhook POSTs from 3rd-party systems. MCPG exposes /webhooks/resource-updated/{token} and triggers notifications/resources/updated when a POST is received.

  • token: string

• sql_polling — SQL polling watch — dev.mcpg.watch.sql_polling plugin runs a scalar tracking query on a cadence and emits an event when the returned scalar advances. Spec mirrors the [bindings.sql] shape (driver, url, optional pool / session_vars, required query block, interval_ms); see the SQL binding plugin docs for the full field list. Pass-through here keeps the spec the single source of truth in the plugin crate.

• postgres_listen_notify — Postgres LISTEN/NOTIFY watch — dev.mcpg.watch.postgres_listen_notify plugin holds one dedicated connection per watch and re-emits NOTIFY payloads. Far lower overhead than polling for change-feed-style sources.

  • channel: string
  • url: string