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.

Two YAML conveniences are resolved before that check: merge keys (<<: *anchor) are applied, and a top-level key that starts with x- is set aside, so a file can keep shared anchors in an x- block (as in Compose files). Below the top level an x- key is an ordinary field name.

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. A CEL predicate references the principal's tenant claim. A governance.policy.tool_access.rules[] entry names one exact tool, never a pattern, so a whole name prefix is matched in the global cel_allow_if, which runs for every call and every list entry (a single binding can instead carry its own governance.allow_if):

   yamlCopy

   governance:
     policy:
       tool_access:
         default_minimum_trust: verified
         cel_allow_if: >-
           (!tool_name.startsWith("acme.")
             || ("tenant" in identity.attributes && identity.attributes["tenant"] == "acme")
             || "platform" in identity.groups)
           && (!tool_name.startsWith("partner.")
             || ("tenant" in identity.attributes && identity.attributes["tenant"] == "partner"))
         # shared.* passes both clauses: any verified caller may use it.
   

   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. secret.X is resolved at config-load too, but the gateway watches the directory and reloads itself when a file changes, so a rotated file reaches new calls within one poll interval. 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.

AauthResourceMetadataConfig

AAuth resource metadata (/.well-known/aauth-resource.json, draft-hardt-oauth-aauth-protocol "Resource Metadata"). Field names follow the spec so an operator can paste a spec-shaped document; unrecognized spec fields ride through extra verbatim.

AauthSigningKeyConfig

Where the AAuth resource signing key comes from — exactly one source.

AccessConfig

AdminAuthConfig

Variants:

• static_bearer

  • bearer_token_env: string
  • read_bearer_token_env: string (optional)

• 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

AdmissionOnError

The decision when the admission tool gives none.

Allowed values:

• deny
• allow

AgentExtensionsConfig

Where a Personal Agent's extensions are read.

AgentExtensionsSource

See [AgentExtensionsConfig::source].

Allowed values:

• client_metadata
• attribute
• none

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

AuditArguments

See [EventTypeAuditConfig::arguments].

Allowed values:

• hash
• raw
• none

AuditConfig

governance.audit: block. Kept apart from 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.

AuditSinkConfig

One entry of governance.audit.sinks.

AuditSinkRouting

Action filters of one audit sink. Patterns are globs over the record's action (* matches any run), e.g. mcpg.resource.*.

AuthConfig

How MCPG authenticates to the upstream.

AuthMode

Identity-propagation mode: what the gateway presents to the upstream.

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

AuthorizationDetailLocations

What the locations of an authorization details object may name.

Variants:

• resource — A resource identifier of this server.

• any — Any string.

AuthorizationDetailsConfig

Rich Authorization Requests (RFC 9396) at the embedded authorization server (governance.access.authorization_server.authorization_details). Off while types is empty: an ID-JAG that carries authorization_details is then refused (invalid_grant), and the authorization_details request parameter is ignored. Turn it on only after every replica runs a build that knows this block: a replica without it drops the details of a sign-in's grant when it rotates the grant's refresh token, and the grant's next tokens carry none. Turning it on (a non-empty types) requires a license with the oauth.rich_authorization feature; a block without a type needs none.

AuthorizationDetailsTypeConfig

One authorization details type the server accepts.

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

A budget is counted in the quota store with atomic counters per window, so it is one budget for every replica that shares the store. A call counts itself before it runs: cap_calls is exact. Tokens and cost are charged after the call from the usage its backend reports (the LLM chat and embedding backends report it; the cost comes from their rate card), so a call runs while the spend is under the cap and the call that crosses it can go over by its own spend.

BuiltinEventSource

An event the gateway raises itself.

Variants:

• mcp.task.updated — A task of the subscriber changed status. Delivered only to the principal whose session owns the task.

• approval.requested — A tool gate asked a person to approve a call.

• approval.resolved — An approval was granted, denied or ran out of time.

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

ClientAuthMethod

A token endpoint client authentication method (RFC 7591 §2).

Allowed values:

• client_secret_basic
• client_secret_post
• private_key_jwt
• none

ClientCertMode

Operator-facing client-cert acceptance mode.

Allowed values:

• none
• optional
• mandatory

ClientConsent

When a registered client's user sees the consent page.

Variants:

• auto — Skip it when every redirect URI is https://, else ask.

• always — Always ask.

• skip — Never ask; refused for a client with a loopback redirect URI, which any local program can receive.

ClientGrantType

A grant type a registered client may use.

Variants:

• urn:ietf:params:oauth:grant-type:jwt-bearer — Redeem an ID-JAG (urn:ietf:params:oauth:grant-type:jwt-bearer).

• authorization_code — Interactive sign-in with PKCE.

• refresh_token — Refresh an interactive grant.

ClientIdMetadataDocumentsConfig

Client ID Metadata Documents at the embedded authorization server (governance.access.authorization_server.client_id_metadata_documents).

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 | 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. When cluster.readiness_gate is unset the effective value is kind-dependent — off for single_node, degrade for every other kind ([ClusterConfig::effective_readiness_gate]).

Variants:

• off — Coordinator health never affects /ready (fail-open). The default for kind: single_node.

• degrade — Surface a not-ready check in the readiness body when the coordinator is down, but keep the overall /ready status green. The default for every clustered (non-single_node) kind.

• 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 -33010 IdempotencyConflict (HTTP 422).

ConsentConfig

The consent page (interactive.consent). It is shown to every dynamically registered client, to every metadata-document client and to a registered client whose redirect URIs are not all https (see clients[].consent), before the user is sent to the IdP.

ControlEnvelopeKind

A webhook control envelope the gateway may send.

Variants:

• gap — Events were skipped; carries the cursor to persist.

• terminated — The subscription ended on the gateway's side.

ControlPlaneAttachConfig

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

CorsConfig

gateway.server.cors — who may call this gateway from a browser page.

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

DeliveryAuditMode

Granularity of delivery audit records.

Variants:

• summary — Counts per subscription per window.

• every — One record per delivery request.

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

DpopConfig

DPoP (RFC 9449) at the embedded authorization server (governance.access.authorization_server.dpop). Off by default: the token endpoint then ignores DPoP headers and the dpop_jkt parameter, and an ID-JAG bound to a key (cnf) is refused. Turn it on only after every replica runs a build that knows this block: a replica without it drops the key binding of a sign-in's grant when it rotates the grant's refresh token. Turning it on (enabled: true) requires a license with the oauth.dpop feature; a block that leaves it off needs none.

DpopNonceMode

Where a DPoP proof must carry a server-provided nonce.

Variants:

• off — No nonce is required.

• token_endpoint — At the token endpoint.

• always — At the token endpoint and at the resource.

DynamicClientRegistrationConfig

Dynamic client registration (interactive.dynamic_client_registration, RFC 7591) at POST /oauth/register, for MCP clients that have neither a clients[] entry nor a Client ID Metadata Document. A registered client is public (token_endpoint_auth_method: none, PKCE), may use only authorization_code and, when it registers it, refresh_token, never redeems ID-JAGs, always sees the consent page (an approval is never remembered), and never satisfies a non-empty trusted_idps[].allowed_clients. What a client registers is its own claim (RFC 7591 §5): the gateway keeps its redirect URIs, grant types, client_name (shown on the consent page as unverified), application_type and, while dpop.enabled, dpop_bound_access_tokens (RFC 9449 §5.2), and ignores every other member, logos and URLs included. A registration is kept sealed like every sign-in record and removed after client_ttl_secs without use; the client is then unknown, and a grant of it is revoked when the client next presents one of that grant's tokens at the token or revocation endpoint.

EnumSource

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

EventAudience

Whose credential reads an event source.

Variants:

• shared — The gateway's own identity; one source serves every subscriber.

• per_principal — Each subscriber's own credential. No source kind of this build reads with a subscriber's credential, so this is refused.

EventDeliveryMode

A delivery mode of an event type.

Variants:

• poll — events/poll.

• push — events/stream.

• webhook — events/subscribe with a callback URL.

EventErrorCodes

The numbering of the MCP Events error codes on the wire.

Variants:

• draft — -32011 to -32015.

• sep_3415 — -32023 to -32027.

EventLogConfig

events.log: — the inbox that inbound routes write before an event reaches the log.

EventReplay

Whether a type's log serves replay.

Variants:

• log — Cursors resume from the log within retention.

• none — No cursor is issued; every subscription starts from now.

EventRetentionConfig

retention: — the bounds of one type's log. The oldest occurrences are evicted first; an append is never refused. On a gateway a control plane manages, the plan's retention caps are the most each bound can be.

EventSourceConfig

The source of an event type: exactly one of watch, inbound, resource or builtin.

EventSourcesConfig

events.sources: — when event sources run.

EventTransformConfig

An operator transform of occurrence data.

EventTypeAuditConfig

mcp.capabilities.events[].audit.

EventTypeConfig

One event type the gateway offers (mcp.capabilities.events[]).

A type binds exactly one source. Subscription arguments are a filter applied by match, never a parameter of the source.

EventWatchSourceConfig

source.watch: — a plugin watch strategy.

EventsAdvertiseLocation

A place in the server/discover capabilities where MCP Events is advertised.

Variants:

• capability — The top-level capabilities.events object.

• extension — The capabilities.extensions["io.modelcontextprotocol/events"] entry.

EventsAuditConfig

events.audit: — how delivery is audited.

EventsConfig

events: config — the experimental MCP Events extension.

Off by default. With enabled: false the events/* methods answer -32601 and server/discover does not mention events. The extension is served on the 2026-07-28 wire over HTTP only; the 2025-11-25 wire and stdio never carry it. Event types are declared under mcp.capabilities.events.

EventsPollConfig

events.poll: — events/poll: a client reads a type's log itself, on any replica, with the cursor of its previous poll. Off by default.

EventsPushConfig

events.push: — events/stream: one long-lived response per subscription, on the replica the client reaches. Off by default.

EventsWebhookConfig

events.webhook: — the webhook delivery profile.

FailureRate

A share between 0 and 1.

Type: number

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.

FederationEventsConfig

How imported MCP Events types are read from the upstream.

FilterConfig

Allow/deny filtering of imported tool and event type 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.

HmacAlgorithm

The hash of an HMAC signature.

Variants:

• sha1 — HMAC-SHA1, 20-byte digests.

• sha256 — HMAC-SHA256, 32-byte digests.

• sha512 — HMAC-SHA512, 64-byte digests.

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.

IdpSessionsConfig

The stored IdP sign-in (interactive.idp_sessions): one per user, shared by every MCP client of that user, used only toward the IdP token endpoint that issued it (to check the sign-in, and as the RFC 8693 subject token of an idp_refresh_token or idp_id_token federation). It is never given to an MCP client.

ImportConfig

Which capability surfaces to import.

InboundHandshakeConfig

An entry of handshakes: — a request the route answers itself.

InboundProfileConfig

An entry of inbound_profiles: — how one kind of sender signs its webhooks: an HMAC of a message built from the raw body, a signed timestamp and headers. Routes name it in verify.profile.

InboundRateLimitConfig

Request rate of one inbound source on each replica.

InboundSourceConfig

source.inbound: — a signed inbound webhook route.

InboundValueConfig

A value of the request. Name exactly one of header and pointer.

InboundVerifyConfig

verify: — how an inbound request proves its sender: a signing profile and this route's secrets.

InboundWhenConfig

when: — the requests an inbound source keeps. Every listed header and every listed body field must match.

InspectorSidecarConfig

InstanceId

Server-assigned stable instance id. Carried as an opaque string so the gateway never needs to parse it; the CP mints it (UUIDv7 today).

Type: string

InteractiveLoginConfig

Settings of interactive sign-in (governance.access.authorization_server.interactive). Every key has a default, so the block is needed only to change one; it is refused without a trusted_idps[].login entry. Requires a license with the sso.interactive_login feature.

InteractiveStoreConfig

Where interactive sign-in state lives (interactive.store).

InteractiveStoreKind

Kind of interactive.store.

Allowed values:

• cluster
• memory
• file

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

The licence of a gateway that mcpg.cloud does not license. A gateway mcpg.cloud delivers a licence to — the delivery carries a proof, signed with an MCPG key, that mcpg.cloud made it on that very connection — ignores the whole block (token, token_file and non_production_use) and runs on that licence, so a config never chooses its own licence there. Under a customer's own control plane, and until a delivery arrives, the block counts, and takes precedence over a self-host licence that control plane relays.

LoginAssertionAudience

The aud of the client assertion.

Variants:

• token_endpoint — The URL of the IdP endpoint the assertion is posted to: the token endpoint, or the revocation endpoint when revoking.

• issuer — The IdP's issuer identifier.

LoginClientAuth

How the gateway authenticates at the IdP token endpoint.

Allowed values:

• client_secret_basic
• client_secret_post
• private_key_jwt

LoginSigningAlg

JWS algorithm of the client assertion the gateway signs.

Allowed values:

• RS256
• PS256
• ES256
• EdDSA

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.