Deploy in Distributed Mode

Deploy in Distributed mode to maintain local control over MCP server definitions while receiving security policies and organization settings from the Control Plane.

Prerequisites

Golf Gateway account with gateway created
Docker or Kubernetes environment (with Redis available)
Local YAML configuration file

Golf Gateway requires Redis for session management, rate limiting, replay protection, and authentication caching. Ensure Redis is available before deploying.

When to use Distributed Mode

Distributed mode is ideal when you need:

Local control over MCP server definitions
Central management of security policies
Gradual migration to full Centralized mode management

Create the configuration file

Create golf-gateway.yaml. The control_plane section activates Distributed mode — the gateway reads servers from this YAML file while fetching organization policies from the Control Plane.

version: "1.0"

# Control Plane connection (activates distributed mode)
control_plane:
  api_key: ${GOLF_GATEWAY_API_KEY}
  gateway_id: ${GOLF_GATEWAY_ID}

servers:
  - name: github-mcp
    url: http://localhost:3001
    description: "GitHub MCP Server"
    server_type: third_party
    rbac_enabled: true
    allowed_groups:
      - developers
      - devops

  - name: slack-mcp
    url: http://localhost:3002
    description: "Slack MCP Server"
    server_type: inhouse
    allowed_groups:
      - all-users

Treat your configuration file as a secret. The YAML file may contain sensitive information such as server URLs, group names, and policy configurations. Never commit it to version control unencrypted.For production deployments, store your configuration in:

AWS Secrets Manager with External Secrets Operator
HashiCorp Vault with External Secrets Operator
Kubernetes Secrets (not ConfigMaps)

Deploy with YAML config

Docker Compose
Kubernetes Secret

version: "3.8"
services:
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 3

  golf-gateway:
    image: ghcr.io/golf-mcp/golf-gateway-backend:latest
    ports:
      - "8080:8080"
    volumes:
      - ./golf-gateway.yaml:/app/golf-gateway.yaml:ro
    environment:
      # These env vars are referenced by ${} in the YAML file
      GOLF_GATEWAY_API_KEY: <your-api-key>
      GOLF_GATEWAY_ID: <your-gateway-id>
      GOLF_GATEWAY_EXTERNAL_URL: https://gateway.example.com
      GOLF_CACHE_REDIS_URL: redis://redis:6379/0
    depends_on:
      redis:
        condition: service_healthy

apiVersion: v1
kind: Secret
metadata:
  name: golf-gateway-config
type: Opaque
stringData:
  golf-gateway.yaml: |
    version: "1.0"
    control_plane:
      api_key: ${GOLF_GATEWAY_API_KEY}
      gateway_id: ${GOLF_GATEWAY_ID}
    servers:
      - name: github-mcp
        url: http://github-mcp-service:3001
        rbac_enabled: true
        allowed_groups:
          - developers
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: golf-gateway
spec:
  template:
    spec:
      containers:
      - name: golf-gateway
        env:
        - name: GOLF_GATEWAY_EXTERNAL_URL
          value: "https://gateway.example.com"
        - name: GOLF_CACHE_REDIS_URL
          value: "redis://redis:6379/0"
        volumeMounts:
        - name: config
          mountPath: /app/golf-gateway.yaml
          subPath: golf-gateway.yaml
          readOnly: true
      volumes:
      - name: config
        secret:
          secretName: golf-gateway-config

For production, use External Secrets Operator to sync from AWS Secrets Manager or HashiCorp Vault.

Golf Gateway offers additional Helm charts for different deployment scenarios. Contact the Golf team for more details on available charts and enterprise deployment options.

What comes from where

Configuration	Centralized	Distributed
MCP server definitions	Control Plane	YAML file
Server-level RBAC	Control Plane	YAML file
Gateway-level policy	Control Plane	YAML file
Security engine settings	Control Plane	YAML file
Exporters	Control Plane	YAML file
Org-wide policies	Control Plane	Control Plane

Verify Distributed mode

Check health endpoint:
curl http://localhost:8080/health
Verify servers synced to Control Plane:
- In Admin Portal, go to MCP Servers
- Your YAML-defined servers appear with a YAML badge

Changes to the YAML file are detected automatically. The gateway reloads configuration without restart.

Deploy in Centralized Mode - Full Centralized mode management
YAML Configuration Schema - Complete YAML reference

Overview

Guides

Reference

Support

Prerequisites

When to use Distributed Mode

Create the configuration file

Deploy with YAML config

What comes from where

Verify Distributed mode

​Prerequisites

​When to use Distributed Mode

​Create the configuration file

​Deploy with YAML config

​What comes from where

​Verify Distributed mode

​Related guides

Prerequisites

When to use Distributed Mode

Create the configuration file

Deploy with YAML config

What comes from where

Verify Distributed mode

Related guides