YAML Configuration Schema

Golf Gateway supports YAML configuration for Distributed mode deployments, where server configurations are defined locally in a YAML file while organization policies and monitoring are managed through the Control Plane. This reference documents the complete YAML schema with all fields, types, and validation rules.

When to Use YAML Configuration

Use YAML configuration when you want to:

Version control your MCP server configurations alongside your infrastructure code
GitOps workflows where server definitions are managed through pull requests
Local server definitions while still benefiting from Control Plane’s centralized policy management and monitoring

YAML configuration works in Distributed mode only. The mode is auto-detected: when a control_plane section is present in the YAML, the gateway runs in Distributed mode. For fully managed deployments without local configuration files, use Centralized mode where all settings are managed through the Golf Control Plane.

Quick Start Example

Here’s a complete, annotated configuration showing the most common settings:

golf-gateway.yaml

# ============================================================
# Golf Gateway Configuration - Distributed Mode
# ============================================================
# Schema version (required, must be "1.0")
version: "1.0"

# -------------------- Control Plane Connection ---------------
# Required for distributed mode - get these values from Control Plane
# Mode is auto-detected: control_plane present = distributed mode
control_plane:
  url: https://control-plane.example.com
  api_key: ${GOLF_CP_API_KEY}
  gateway_id: 550e8400-e29b-41d4-a716-446655440000

# -------------------- Identity Providers --------------------
# Configure OAuth/OIDC providers for authentication
identity_providers:
  - name: auth0                              # Unique name (referenced by servers)
    type: auth0                              # auth0, microsoft-entra-id, descope
    issuer: https://myorg.auth0.com/
    jwks_uri: https://myorg.auth0.com/.well-known/jwks.json
    api_identifiers:
      - https://api.example.com              # Must match JWT audience
    # Management API credentials (optional, for group sync)
    client_id: ${AUTH0_MGMT_CLIENT_ID}       # Environment variable substitution
    client_secret: ${AUTH0_MGMT_CLIENT_SECRET}

# -------------------- MCP Servers ---------------------------
# Configure upstream MCP servers with RBAC
servers:
  - name: github-mcp                         # Unique server name
    url: http://github-mcp:3001              # Server URL
    description: "GitHub integration"
    server_type: third_party                 # third_party or inhouse
    enabled: true

    # RBAC: Control who can access this server
    rbac_enabled: true
    rbac_mode: allow                         # allow (whitelist) or deny (blacklist)
    allowed_groups:
      - engineering
      - devops

    # Link to identity provider for group resolution
    idp: auth0

    # Per-server PII scrubbing overrides (merged with gateway defaults)
    security:
      enabled: true
      sensitive_fields: [token, password]    # Additional fields to mask
      whitelist_fields: [cursor, tool_name]  # Fields to never scrub

  - name: internal-tools
    url: http://tools-mcp:3002
    server_type: inhouse                     # auto-maps to visibility: internal
    rbac_enabled: false                      # No RBAC for internal tools

# -------------------- Gateway Policy -------------------------
gateway_policy:
  scrubbing:
    enabled: true
    sensitive_fields: [password, api_key]
  server_rbac:
    rbac_enabled: true
    rbac_mode: allow
    allowed_groups: [gateway-users]

# -------------------- Security Engine -------------------------
security:
  replay_protection:
    enabled: true
  rate_limiting:
    enabled: true
    requests_per_minute: 100                 # Per-user limit
    window_seconds: 60

# -------------------- Audit Log Export ----------------------
exporters:
  elasticsearch:
    - name: primary
      enabled: true
      url: ${ELASTICSEARCH_URL}              # Self-hosted URL
      api_key: ${ELASTICSEARCH_API_KEY}
      index_prefix: golf-gateway             # Creates: golf-gateway-YYYY.MM.DD

Use ${VAR} for required environment variables or ${VAR:default} for optional ones with defaults.

Scroll down for detailed documentation of each section.

File Location

The gateway searches for configuration files in this order:

GOLF_CONFIG_FILE environment variable (explicit path)
/etc/golf-gateway/config.yaml
/etc/golf-gateway/config.yml
./golf-gateway.yaml (current directory)
./golf-gateway.yml (current directory)

# Explicit path
export GOLF_CONFIG_FILE=/path/to/config.yaml

Environment Variable Interpolation

YAML configuration supports environment variable substitution:

Syntax	Behavior
`${VAR}`	Required - fails if `VAR` is not set
`${VAR:default}`	Optional - uses `default` if `VAR` is not set

# Required variable (fails if not set)
api_key: ${GOLF_API_KEY}

# Optional with default
timeout: ${GOLF_TIMEOUT:30}

# In nested structures
servers:
  - name: github-mcp
    url: ${MCP_SERVER_URL:http://localhost:3001}

Root Configuration

version: "1.0"                    # Required, only "1.0" supported

control_plane:                    # Presence activates distributed mode
  url: https://control-plane.example.com
  api_key: ${GOLF_CP_API_KEY}
  gateway_id: 550e8400-e29b-41d4-a716-446655440000

# Optional sections
identity_providers: []
servers: []
gateway_policy: {}
security: {}
oauth_server: {}
exporters: {}

Root Fields

Field	Type	Required	Default	Description
`version`	string	Yes	-	Schema version, must be `"1.0"`
`control_plane`	object	No	-	Control Plane connection settings. Presence activates Distributed mode; absence means Standalone mode.
`identity_providers`	array	No	`[]`	Identity provider configurations
`servers`	array	No	`[]`	MCP server configurations
`gateway_policy`	object	No	`{}`	Gateway-level policy defaults
`security`	object	No	`{}`	Security engine settings (replay protection, rate limiting)
`oauth_server`	object	No	`{}`	Gateway’s MCP OAuth authorization server configuration
`exporters`	object	No	`{}`	Log export destinations

The deployment mode is auto-detected: if control_plane is present, the gateway runs in Distributed mode. If absent, it runs in Standalone mode. No explicit mode field is needed.

Identity Providers

Configure OAuth/OIDC identity providers for authentication.

identity_providers:
  - name: auth0-primary
    type: auth0
    issuer: https://myorg.auth0.com/
    jwks_uri: https://myorg.auth0.com/.well-known/jwks.json
    api_identifiers:
      - https://api.example.com
    client_id: ${AUTH0_CLIENT_ID}
    client_secret: ${AUTH0_CLIENT_SECRET}

  - name: descope-corp
    type: descope
    project_id: ${DESCOPE_PROJECT_ID}
    management_key: ${DESCOPE_MANAGEMENT_KEY}
    # issuer and jwks_uri auto-generated for Descope

Identity Provider Fields

Field	Type	Required	Description
`name`	string	Yes	Unique provider name (1-255 chars)
`type`	enum	Yes	`auth0`, `microsoft-entra-id`, `descope`
`issuer`	string	Conditional	OIDC issuer URL (auto-generated for Descope)
`jwks_uri`	string	Conditional	JWKS endpoint URL (auto-generated for Descope)
`userinfo_endpoint`	string	No	Userinfo endpoint URL
`api_identifiers`	array	No	API audience identifiers
`timeout`	int	No	Request timeout in seconds (default: 10, range: 1-60)
`client_id`	string	No	Management API client ID (for group sync)
`client_secret`	string	No	Management API client secret
`tenant_id`	string	Conditional	Tenant ID. Required for Entra ID (Azure AD tenant). Optional for Descope (tenant-scoped operations).

Descope-Specific Fields

Field	Type	Required	Description
`project_id`	string	Yes (Descope)	Descope Project ID
`management_key`	string	No	Descope Management Key for group sync

Servers

Configure MCP upstream servers with RBAC and security settings.

servers:
  - name: github-mcp
    url: http://github-mcp:3001
    description: "GitHub integration server"
    server_type: third_party
    enabled: true

    # RBAC
    rbac_enabled: true
    rbac_mode: allow
    allowed_groups:
      - engineering
      - devops

    # Capability RBAC
    capability_rbac_enabled: true
    capability_overrides:
      - capability: "tools/delete_repo"
        rbac_enabled: true
        rbac_mode: allow
        allowed_groups: [repo-admins]

    # Per-server PII scrubbing overrides (merged with gateway defaults)
    security:
      enabled: true
      sensitive_fields: [password, token]
      whitelist_fields: [cursor, tool_name]
      recognizers:
        - entity_type: EMAIL_ADDRESS
          enabled: true
          replacement: "[PII_EMAIL]"

    # Identity provider reference
    idp: auth0-primary

Server Schema

servers

array

List of upstream MCP server configurations.

Hide server object

name

string

required

Unique server name (1-255 characters). Used as identifier in logs and routing.

url

string

required

Server URL (e.g., http://mcp-server:3001).

description

string

default:"\"\""

Human-readable server description.

server_type

enum

default:"third_party"

Server classification: inhouse or third_party.

enabled

boolean

default:"true"

Enable or disable this server.

visibility

enum

default:"third_party"

Visibility level: third_party, internal, or public.

upstream_auth_type

enum

default:"oauth"

Authentication type for upstream: oauth, none, or api_key.

session_affinity

boolean

default:"true"

Maintain session affinity to the same upstream instance.

idp

string

Reference to an identity provider name for group resolution.

rbac_enabled

boolean

default:"false"

Enable server-level role-based access control.

rbac_mode

enum

default:"allow"

RBAC mode: allow (whitelist) or deny (blacklist).

allowed_groups

array

default:"[]"

Groups with access when rbac_mode: allow.

denied_groups

array

default:"[]"

Groups denied access when rbac_mode: deny.

rbac_audit

boolean

default:"true"

Log RBAC access decisions to audit log.

capability_rbac_enabled

boolean

default:"false"

Enable per-capability RBAC overrides.

capability_overrides

array

Per-capability RBAC rules that override server-level settings.

Show capability override object

capability

string

required

Capability pattern (e.g., tools/*, resources/file, tools/delete_repo).

rbac_enabled

boolean

default:"true"

Enable RBAC for this specific capability.

rbac_mode

enum

default:"allow"

RBAC mode for this capability: allow or deny.

allowed_groups

array

Groups with access to this capability.

preregistered_client_id

string

Pre-registered OAuth client ID for this server (bypasses Dynamic Client Registration).

preregistered_client_secret

string

Pre-registered OAuth client secret for this server.

auth_server_url

string

OAuth issuer URL override. Set when the upstream doesn’t publish discovery metadata at its resource origin.

scopes_override

string

Space-separated OAuth scopes to request, replacing those advertised in discovery.

security

object

Per-server PII scrubbing overrides. These settings are merged on top of gateway-level defaults using union merge.

Show properties

enabled

boolean

default:"false"

Enable PII scrubbing for this server’s traffic.

sensitive_fields

array

default:"[]"

Additional field names to mask (e.g., password, api_key). Merged via union with gateway-level fields.

whitelist_fields

array

default:"[]"

Field names that should never be scrubbed, even if they match PII patterns (e.g., cursor, tool_name).

custom_rules

array

default:"[]"

Custom regex-based scrubbing rules.

Show custom rule object

pattern

string

required

Regex pattern to match sensitive content.

method

enum

required

Masking method: mask, remove, hash, or replace.

replacement

string

Custom replacement text (required when method is replace).

recognizers

array

default:"[]"

Toggle and configure built-in PII recognizers. When merging across layers, enabled: true wins over enabled: false (most-restrictive doctrine).

Show recognizer config object

entity_type

string

required

Entity type (e.g., EMAIL_ADDRESS, CREDIT_CARD, US_SSN).

enabled

boolean

default:"true"

Enable or disable this recognizer.

replacement

string

Custom replacement text for this entity type (e.g., [PII_EMAIL]). Per-server replacements override gateway defaults.

Gateway Policy

Gateway-level policy defaults that apply to all servers unless overridden. In distributed mode, these are merged with organization policies from the Control Plane.

gateway_policy:
  scrubbing:
    enabled: true
    sensitive_fields:
      - password
      - api_key
    whitelist_fields:
      - connection_id
      - session_id
      - cursor
    custom_rules:
      - pattern: "sk-[a-zA-Z0-9]+"
        method: mask
    recognizers:
      - entity_type: EMAIL_ADDRESS
        enabled: true
      - entity_type: URL
        enabled: false        # Disable URL scrubbing

  server_rbac:
    rbac_enabled: true
    rbac_mode: allow
    allowed_groups: [gateway-users]
    denied_groups: []
    capability_rbac_enabled: false

  capability_rbac:
    read_only:
      default_groups: [all-users]
    destructive:
      default_groups: [power-users]
    unspecified:
      default_groups: [all-users]

Scrubbing Policy

The scrubbing configuration uses the same schema at both gateway and server levels. All fields are merged using union — if any layer adds a field or rule, it applies.

Field	Type	Default	Description
`enabled`	bool	`false`	Enable PII scrubbing
`sensitive_fields`	array	`[]`	Field names to always mask as `[MASKED]`
`whitelist_fields`	array	`[]`	Field names that should never be scrubbed (protects operational data)
`custom_rules`	array	`[]`	Custom regex-based scrubbing rules (see server security for schema)
`recognizers`	array	`[]`	Toggle and configure built-in PII recognizers

When recognizer configs are merged across layers (org → gateway → server), enabled: true wins over enabled: false (most-restrictive doctrine). Server-specific replacement text overrides gateway defaults.

Server RBAC Policy

Field	Type	Default	Description
`rbac_enabled`	bool	`false`	Default RBAC enabled for new servers
`rbac_mode`	enum	`allow`	Default RBAC mode
`allowed_groups`	array	`[]`	Default allowed groups
`denied_groups`	array	`[]`	Default denied groups
`capability_rbac_enabled`	bool	`false`	Default capability RBAC enabled

Capability RBAC Policy

Field	Type	Description
`read_only.default_groups`	array	Default groups for read-only tools
`destructive.default_groups`	array	Default groups for destructive tools
`unspecified.default_groups`	array	Default groups for unclassified tools

Local Servers Policy

Controls the gateway-level blocking policy for locally-defined servers.

Field	Type	Default	Description
`enabled`	bool	`false`	Enable local server blocking policy
`mode`	enum	`allow`	Blocking mode: `allow` or `deny`
`groups`	array	`null`	Groups affected by this policy

Security

The security section controls replay protection and rate limiting. This is operational configuration, not policy — it does not participate in the org → gateway → server policy merge cascade.

security:
  replay_protection:
    enabled: true

  rate_limiting:
    enabled: true
    requests_per_minute: 100
    window_seconds: 60

Replay Protection

Field	Type	Default	Description
`enabled`	bool	`true`	Enable replay attack protection

Rate Limiting

Field	Type	Default	Range	Description
`enabled`	bool	`true`	-	Enable rate limiting
`requests_per_minute`	int	`1000`	1-5000	Requests per minute per user
`window_seconds`	int	`60`	10-300	Rate limit window

YAML configures the per-user limit only. System-wide (global) and per-server limits are managed through the Control Plane. See Configure Rate Limiting for the full model.

OAuth Server

Configure the gateway’s MCP OAuth authorization server for third-party server authentication flows.

oauth_server:
  token_ttl: 3600
  refresh_token_ttl: 604800
  authorization_code_ttl: 60
  idp_client_id: ${GOLF_OAUTH_SERVER_IDP_CLIENT_ID}
  idp_client_secret: ${GOLF_OAUTH_SERVER_IDP_CLIENT_SECRET}

Field	Type	Default	Range	Description
`issuer`	string	gateway URL	-	OAuth issuer URL
`token_ttl`	int	`3600`	300-86400	Access token TTL in seconds
`refresh_token_ttl`	int	`604800`	3600-2592000	Refresh token TTL in seconds
`authorization_code_ttl`	int	`60`	30-600	Authorization code TTL in seconds
`idp_client_id`	string	-	-	IdP client ID for the OAuth server
`idp_client_secret`	string	-	-	IdP client secret (supports `${ENV_VAR}`)

Exporters

Configure multiple export destinations for audit logs. You can configure multiple exporters of each type.

exporters:
  elasticsearch:
    - name: primary-es
      enabled: true
      url: ${ELASTICSEARCH_URL}
      api_key: ${ELASTICSEARCH_API_KEY}
      index_prefix: golf-gateway
      timeout: 30

  otel:
    - name: primary-otel
      enabled: true
      endpoint: ${OTEL_ENDPOINT}
      protocol: grpc
      service_name: golf-gateway
      export_logs: true

  sentinel:
    - name: azure-sentinel
      enabled: true
      dcr_immutable_id: ${SENTINEL_DCR_ID}
      dcr_endpoint: ${SENTINEL_DCR_ENDPOINT}
      tenant_id: ${AZURE_TENANT_ID}
      client_id: ${AZURE_CLIENT_ID}
      client_secret: ${AZURE_CLIENT_SECRET}

Exporter Schema

exporters

object

Configure audit log export destinations.

Hide exporter types

elasticsearch

array

Elasticsearch export configurations.

Show elasticsearch exporter

name

string

required

Unique exporter name.

enabled

boolean

default:"true"

Enable this exporter.

url

string

Elasticsearch URL for self-hosted deployments (e.g., https://localhost:9200).

cloud_id

string

Elastic Cloud ID (alternative to url).

api_key

string

API key for authentication.

index_prefix

string

default:"golf-gateway"

Index name prefix. Creates indices like golf-gateway-2024.01.15.

timeout

integer

default:"30"

Request timeout in seconds (5-120).

otel

array

OpenTelemetry export configurations.

Show otel exporter

name

string

required

Unique exporter name.

enabled

boolean

default:"true"

Enable this exporter.

endpoint

string

required

OTLP endpoint URL (e.g., http://localhost:4317).

protocol

enum

default:"grpc"

OTLP protocol: grpc, http/protobuf, or http/json.

service_name

string

default:"golf-gateway"

Service name in OpenTelemetry.

timeout

integer

default:"30"

Export timeout in seconds (5-120).

export_logs

boolean

default:"true"

Export audit logs as OTLP logs.

export_metrics

boolean

default:"false"

Export gateway metrics.

export_traces

boolean

default:"false"

Export request traces.

headers

object

default:"{}"

Additional HTTP headers (e.g., Authorization: Bearer TOKEN).

sentinel

array

Microsoft Sentinel export configurations.

Show sentinel exporter

name

string

required

Unique exporter name.

enabled

boolean

default:"true"

Enable this exporter.

dcr_immutable_id

string

required

Data Collection Rule immutable ID.

dcr_endpoint

string

required

DCR logs ingestion endpoint (HTTPS URL).

dcr_stream_name

string

default:"Custom-GolfGateway_CL"

DCR stream name for the custom table.

tenant_id

string

required

Azure AD tenant ID.

client_id

string

required

Service principal client ID.

client_secret

string

required

Service principal client secret.

timeout

integer

default:"30"

Request timeout in seconds (5-120).

For Elasticsearch, use either url (self-hosted) or cloud_id (Elastic Cloud), not both.

Control Plane Connection

Connects the gateway to the Control Plane for centralized policy management and monitoring. The presence of this section activates Distributed mode.

control_plane:
  url: https://control-plane.example.com
  api_key: ${GOLF_CP_API_KEY}
  gateway_id: 550e8400-e29b-41d4-a716-446655440000
  timeout: 30
  cache_ttl: 300

Field	Type	Required	Default	Description
`url`	string	Yes	`https://api.golf.dev`	Control Plane URL
`api_key`	string	Yes	-	API key for authentication (supports `${ENV_VAR}`)
`gateway_id`	UUID	Yes	-	Gateway UUID
`timeout`	int	No	`30`	Request timeout (5-120 seconds)
`cache_ttl`	int	No	`300`	Policy cache TTL in seconds (60-3600)

Complete Example

A complete Distributed mode configuration with Control Plane connection, identity providers, servers, security, and exporters:

version: "1.0"

# Control Plane connection (activates distributed mode)
control_plane:
  url: https://control-plane.example.com
  api_key: ${GOLF_CP_API_KEY}
  gateway_id: 550e8400-e29b-41d4-a716-446655440000

# Identity providers for authentication
identity_providers:
  - name: auth0
    type: auth0
    issuer: https://myorg.auth0.com/
    jwks_uri: https://myorg.auth0.com/.well-known/jwks.json
    api_identifiers:
      - https://api.example.com
    client_id: ${AUTH0_MGMT_CLIENT_ID}
    client_secret: ${AUTH0_MGMT_CLIENT_SECRET}

# MCP servers (YAML is source of truth for servers in distributed mode)
servers:
  - name: github-mcp
    url: http://github-mcp:3001
    server_type: third_party
    rbac_enabled: true
    allowed_groups: [engineering]
    idp: auth0
    security:
      enabled: true
      sensitive_fields: [token]

  - name: internal-tools
    url: http://tools-mcp:3002
    server_type: inhouse
    rbac_enabled: false

# OAuth authorization server for third-party server auth flows
oauth_server:
  idp_client_id: ${GOLF_OAUTH_SERVER_IDP_CLIENT_ID}
  idp_client_secret: ${GOLF_OAUTH_SERVER_IDP_CLIENT_SECRET}

# Local policy (merged with org policy from Control Plane)
gateway_policy:
  scrubbing:
    enabled: true
    sensitive_fields: [ssn, account_number]
    whitelist_fields: [connection_id, session_id]
  server_rbac:
    rbac_enabled: true
    allowed_groups: [gateway-users]

# Security engine settings
security:
  replay_protection:
    enabled: true
  rate_limiting:
    enabled: true
    requests_per_minute: 100

# Audit log exporters
exporters:
  elasticsearch:
    - name: primary
      url: ${ELASTICSEARCH_URL}
      api_key: ${ELASTICSEARCH_API_KEY}

Validation Rules

Version

Must be exactly "1.0"
Required field

Identity Providers

Names must be unique across all providers
For non-Descope providers: issuer and jwks_uri are required
For Descope: project_id is required; issuer and jwks_uri are auto-generated
For Entra ID: tenant_id is required

Servers

Names must be unique across all servers
idp references must match an existing identity provider name
url must be a valid URL
When gateway and server both enable RBAC, their rbac_mode must be consistent (cannot mix allow and deny across policy levels)

Exporters

Names must be unique within each exporter type
Elasticsearch: use url OR cloud_id, not both
OTEL: endpoint required when enabled
Sentinel: all DCR and auth fields required when enabled

Security

rate_limiting.requests_per_minute must be between 1 and 5000 when rate limiting is enabled
rate_limiting.window_seconds must be between 10 and 300 when rate limiting is enabled

Control Plane

When present, url, api_key, and gateway_id are required
organization_id is optional — resolved from Control Plane during activation if not set
Mode is auto-detected: control_plane present = Distributed mode

Configuration Validation CLI

Validate configuration files before deployment:

# The gateway validates config on startup
GOLF_CONFIG_FILE=/path/to/config.yaml python -m golf_gateway.main --validate

# Check for undefined environment variables
GOLF_CONFIG_FILE=/path/to/config.yaml python -c "
from golf_gateway.config.yaml_loader import validate_yaml_config
errors = validate_yaml_config('/path/to/config.yaml')
for error in errors:
    print(error)
"

Environment Variables

Configure Golf Gateway using environment variables

Audit Log Schema

Complete audit log entry structure reference

RBAC Configuration

Set up role-based access control

Deployment Guide

Deploy Golf Gateway to production

​YAML Configuration Schema

​When to Use YAML Configuration

​Quick Start Example

​File Location

​Environment Variable Interpolation

​Root Configuration

​Root Fields

​Identity Providers

​Identity Provider Fields

​Descope-Specific Fields

​Servers

​Server Schema

​Gateway Policy

​Scrubbing Policy

​Server RBAC Policy

​Capability RBAC Policy

​Local Servers Policy

​Security

​Replay Protection

​Rate Limiting

​OAuth Server

​Exporters

​Exporter Schema

​Control Plane Connection

​Complete Example

​Validation Rules

​Version

​Identity Providers

​Servers

​Exporters

​Security

​Control Plane

​Configuration Validation CLI

​Related Documentation

Environment Variables

Audit Log Schema

RBAC Configuration

Deployment Guide

YAML Configuration Schema

When to Use YAML Configuration

Quick Start Example

File Location

Environment Variable Interpolation

Root Configuration

Root Fields

Identity Providers

Identity Provider Fields

Descope-Specific Fields

Servers

Server Schema

Gateway Policy

Scrubbing Policy

Server RBAC Policy

Capability RBAC Policy

Local Servers Policy

Security

Replay Protection

Rate Limiting

OAuth Server

Exporters

Exporter Schema

Control Plane Connection

Complete Example

Validation Rules

Version

Identity Providers

Servers

Exporters

Security

Control Plane

Configuration Validation CLI

Related Documentation