Documentation Index
Fetch the complete documentation index at: https://docs.golf.dev/llms.txt
Use this file to discover all available pages before exploring further.
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.
