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

# Distributed mode: servers from YAML, policies from Control Plane
mode: hybrid

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

# -------------------- Gateway Identity ----------------------
# Required: identifies this gateway instance
gateway:
  id: 550e8400-e29b-41d4-a716-446655440000  # UUID (generate or from Control Plane)
  name: production-gateway                    # Human-readable name
  description: "Main production MCP gateway"  # Optional

# -------------------- Identity Providers --------------------
# Configure OAuth/OIDC providers for authentication
identity_providers:
  - name: auth0                              # Unique name (referenced by servers)
    type: auth0                              # auth0, okta, 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 security settings
    security:
      enabled: true
      sensitive_fields: [token, password]    # Additional fields to mask

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

# -------------------- Rate Limiting -------------------------
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
mode: hybrid                      # Distributed mode for YAML configuration

control_plane:                    # Required - Control Plane connection
  url: https://control-plane.example.com
  api_key: ${GOLF_CP_API_KEY}
  gateway_id: 550e8400-e29b-41d4-a716-446655440000
  organization_id: 660e8400-e29b-41d4-a716-446655440001

gateway:                          # Required - gateway identity
  id: 550e8400-e29b-41d4-a716-446655440000
  name: production-gateway
  description: "Main production gateway"

# Optional sections
identity_providers: []
servers: []
gateway_policy: {}
global_security: {}
rate_limiting: {}
exporters: {}

Root Fields

Field	Type	Required	Default	Description
`version`	string	Yes	-	Schema version, must be `"1.0"`
`mode`	`hybrid`	Yes	-	Must be `hybrid` for Distributed mode YAML configuration
`control_plane`	object	Yes	-	Control Plane connection settings
`gateway`	object	Yes	-	Gateway identity
`identity_providers`	array	No	`[]`	Identity provider configurations
`servers`	array	No	`[]`	MCP server configurations
`gateway_policy`	object	No	`{}`	Gateway-level policy defaults
`global_security`	object	No	`{}`	Global security settings
`rate_limiting`	object	No	`{}`	Rate limiting configuration
`exporters`	object	No	`{}`	Log export destinations

Gateway Identity

Required section that identifies the gateway instance.

gateway:
  id: 550e8400-e29b-41d4-a716-446655440000  # UUID
  name: production-gateway                    # 1-255 characters
  description: "Optional description"

Field	Type	Required	Description
`id`	UUID	Yes	Gateway UUID (from Control Plane or self-assigned)
`name`	string	Yes	Human-readable name (1-255 chars)
`description`	string	No	Optional description

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`, `okta`, `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

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
`tenant_id`	string	No	Tenant ID for tenant-scoped operations

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 security
    security:
      enabled: true
      sensitive_fields: [password, token]

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

security

object

Per-server security and PII scrubbing settings.

Show properties

enabled

boolean

default:"true"

Enable PII scrubbing for this server’s traffic.

sensitive_fields

array

default:"[]"

Additional field names to mask (e.g., password, api_key).

Gateway Policy

Gateway-level policy defaults that apply to all servers unless overridden.

gateway_policy:
  scrubbing:
    enabled: true
    sensitive_fields:
      - password
      - api_key

  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

Field	Type	Default	Description
`enabled`	bool	`true`	Enable PII scrubbing globally
`sensitive_fields`	array	`[]`	Additional sensitive field names

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

Global Security

Global security settings for data scrubbing and PII protection.

global_security:
  data_scrubbing:
    enabled: true
    sensitive_fields: [password, api_key, secret]

Data Scrubbing Fields

Field	Type	Default	Description
`enabled`	bool	`true`	Enable PII scrubbing in audit logs
`sensitive_fields`	array	`[]`	Additional field names to mask

Rate Limiting

rate_limiting:
  enabled: true
  requests_per_minute: 50
  window_seconds: 60

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

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

Required section that connects the gateway to the Control Plane for centralized policy management and monitoring.

mode: hybrid

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

Field	Type	Required	Default	Description
`url`	string	Yes	-	Control Plane URL
`api_key`	string	Yes	-	API key for authentication
`gateway_id`	UUID	Yes	-	Gateway UUID
`organization_id`	UUID	Yes	-	Organization 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, and exporters:

version: "1.0"
mode: hybrid

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

# Gateway identity
gateway:
  id: 550e8400-e29b-41d4-a716-446655440000
  name: production-gateway
  description: "Main production gateway"

# 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

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

# Rate limiting
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

Gateway Identity

id must be a valid UUID
name must be 1-255 characters

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

Servers

Names must be unique across all servers
idp references must match an existing identity provider name
url must be a valid URL

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

Control Plane

control_plane section is required
All Control Plane fields (url, api_key, gateway_id, organization_id) are required
mode must be set to hybrid for 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

Overview

Guides

Reference

Support

​YAML Configuration Schema

​When to Use YAML Configuration

​Quick Start Example

​File Location

​Environment Variable Interpolation

​Root Configuration

​Root Fields

​Gateway Identity

​Identity Providers

​Identity Provider Fields

​Descope-Specific Fields

​Servers

​Server Schema

​Gateway Policy

​Scrubbing Policy

​Server RBAC Policy

​Capability RBAC Policy

​Global Security

​Data Scrubbing Fields

​Rate Limiting

​Exporters

​Exporter Schema

​Control Plane Connection

​Complete Example

​Validation Rules

​Version

​Gateway Identity

​Identity Providers

​Servers

​Exporters

​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

Gateway Identity

Identity Providers

Identity Provider Fields

Descope-Specific Fields

Servers

Server Schema

Gateway Policy

Scrubbing Policy

Server RBAC Policy

Capability RBAC Policy

Global Security

Data Scrubbing Fields

Rate Limiting

Exporters

Exporter Schema

Control Plane Connection

Complete Example

Validation Rules

Version

Gateway Identity

Identity Providers

Servers

Exporters

Control Plane

Configuration Validation CLI

Related Documentation