> ## 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.
# Golf Gateway
> Enterprise security gateway for MCP servers
Golf is the **enterprise MCP platform**. Get centralized control and visibility over all your MCPs, enforce access policies, and integrate with your SIEM.
* **Screen data inputs for hidden instructions** - Our firewall automatically sanitizes tool outputs to block prompt injections before they reach the agent
* **Enforce strict role-based access** - Control which agents can access which servers, tools, and resources
* **Continuous governance through logging** - Every interaction is logged with tamper-proof audit trails
* **Ringfence sensitive data** - Automatically redact PII to prevent leakage from internal LLMs
## The Problem
Traditional API gateways and WAFs were not built for MCP. They see HTTP and JSON, but they don't understand:
* MCP methods, tools, resources, prompts, elicitation, sampling, and other protocol primitives
* Multi-step agent flows and how tools are actually used
* Prompt injection and tool poisoning attempts hiding inside "normal" data
Whether you've blocked AI agents entirely (but employees use them anyway on personal devices) or approved them (but now have fragmented control points across Claude, Cursor, ChatGPT, etc.) - you need a governance layer.
## What Golf Gateway Does
Single control point regardless of which agent (Claude, Cursor, ChatGPT, Copilot) employees use.
Full audit trail for every interaction. Export to your SIEM (Elasticsearch, Sentinel, OTLP).
Centralized RBAC for non-human identities. One policy layer across all your agents and MCP servers.
Block prompt injections before they reach agents. Sanitize tool outputs and redact PII automatically.
Golf Gateway is **protocol-aware**: it understands MCP semantics and uses that to protect your agents and backend systems.
The gateway operates as a **transparent proxy**—neither MCP clients nor servers need modifications:
```mermaid theme={null}
flowchart LR
A["MCP Client"] --> B["MCP Server"]
```
Direct connection. No visibility. No control.
```mermaid theme={null}
flowchart LR
A["MCP Client"] --> B["Golf Gateway"]
B --> C["MCP Server"]
style B fill:#f97728,stroke:#ea580c,color:#ffffff
```
All traffic visible. All access controlled. All actions logged.
To route through the gateway, configure your MCP client to connect to the gateway's URL instead of the MCP server directly:
```json theme={null}
{
"mcpServers": {
"github": {
"url": "https://gateway.company.com/github/mcp"
}
}
}
```
## Security
The firewall is the security analysis engine within Golf Gateway.
### Prompt Injection Detection
The firewall uses an AI model to detect prompt injection attacks in real-time:
1. Content is extracted from MCP messages (tool arguments, resource content)
2. The LLM threat detector analyzes the content
3. When the model finds a prompt injection the request is blocked
The model runs locally within the gateway. This ensures low latency and data privacy.
### Rate Limiting
Protect against abuse with sliding-window rate limiting at three layers:
| Layer | Scope |
| -------------- | ----------------- |
| **Per-User** | Individual user |
| **Per-Server** | Single MCP server |
| **Global** | Entire gateway |
The most restrictive limit applies.
### Replay Protection
Prevent session token theft and reuse:
1. When a session is first used, it's bound to the authenticated user
2. If the same session ID appears with a different user, it's flagged as replay
3. Replay attempts are blocked and logged
### Audit & Visibility
Every request is logged with cryptographic integrity:
* **HMAC-SHA256 hash chain** - Tamper-evident logging
* **Sequence numbers** - Detect missing or reordered entries
* **Rich metadata** - User, server, tool, latency, threat status
This gives you incident response capability and the audit trail compliance teams need.
## Policy Engine
The Policy Engine is the centralized governance system that manages and enforces access control and data protection across Golf Gateway. It operates on a **3-layer hierarchy** where policies at each level can restrict (but never expand) permissions:
```
Organization → Gateway → Server/Capability
```
The Policy Engine manages four policy types:
| Policy | Purpose | Hierarchy |
| ------------------------- | ----------------------------------------------- | -------------------------- |
| **Server RBAC** | Control which groups can access MCP servers | All 3 layers |
| **Capability RBAC** | Control access to tools, prompts, and resources | All 3 layers + annotations |
| **PII Scrubbing** | Detect and mask sensitive data | All 3 layers |
| **Capability Versioning** | Require approval for capability changes | Server only |
### How Policies Merge
Policies follow a **"most restrictive wins"** doctrine. As you move down the hierarchy, policies can only become more restrictive, never less:
| Field | Merge Rule | Behavior |
| --------------------------- | ------------ | --------------------------------------- |
| Enabled flags | OR | True if ANY layer enables |
| Allowed groups (allow mode) | Intersection | User must be in ALL layers' groups |
| Denied groups (deny mode) | Union | Blocked if in ANY layer's deny list |
| Sensitive fields | Union | All fields from all layers are scrubbed |
| Custom rules & entities | Union | Combined from all layers |
```
Organization: allowed_groups = ["admins", "devs", "viewers"]
Gateway: allowed_groups = ["admins", "devs"]
Server: allowed_groups = ["admins"]
Result: Only "admins" can access (intersection of all layers)
```
### Server RBAC
Server RBAC controls which user groups can connect to each MCP server. Configure at any layer to set defaults or restrictions:
| Mode | Behavior |
| ------------------- | ---------------------------------------------------- |
| **Allow** (default) | Only users in `allowed_groups` can access |
| **Deny** | Users in `denied_groups` are blocked, others allowed |
When both modes are configured across layers, deny lists are checked first and take precedence.
### Capability RBAC
Capability RBAC provides fine-grained access control for individual tools, prompts, and resources. It uses a **4-layer merge** that incorporates MCP tool annotations:
Set default groups for each annotation category (read-only, destructive, unspecified)
Override or restrict org defaults (merged via intersection)
Tool annotations determine which policy category applies
Per-tool group restrictions (intersected with policy)
#### Tool Annotations
Annotations are metadata hints that MCP servers provide about their tools. They're part of the [MCP specification](https://modelcontextprotocol.io/specification/2025-03-26/server/tools#annotations) and describe the nature of each tool's behavior—whether it only reads data, makes destructive changes, or falls somewhere in between.
Golf Gateway discovers these annotations automatically when it connects to an MCP server and uses them to apply the appropriate access policy:
| Annotation | Meaning | Policy Category |
| ----------------------- | ----------------------------------------------------------- | --------------- |
| `readOnlyHint: true` | Tool only reads data, no side effects | Read-only |
| `destructiveHint: true` | Tool may perform destructive operations (delete, overwrite) | Destructive |
| Neither annotation | Tool behavior is unspecified or mixed | Unspecified |
You configure these defaults at the organization level:
```
read_only.allowed_groups = ["all-users"]
destructive.allowed_groups = ["admins"]
unspecified.allowed_groups = ["developers", "admins"]
```
When a user invokes a tool:
* `list_files` (readOnlyHint: true) → Allowed for all users
* `delete_file` (destructiveHint: true) → Requires admin group
* `send_message` (no annotations) → Requires developers or admins
This allows you to set broad policies like "all destructive tools require admin access" at the org level, while still allowing per-tool overrides at the capability level when needed.
### PII Scrubbing Policy
PII scrubbing configuration follows the same 3-layer merge. At each layer you can configure:
* **Sensitive fields**: Field names to always mask
* **Pre-built recognizers**: Toggle built-in entity detection (21 types)
* **Custom rules**: Regex patterns with mask/remove/hash/replace methods
* **Custom entities**: AI-powered detection for custom data types
All configurations are merged using union—if any layer adds a field or rule, it applies.
### Capability Versioning
Unlike RBAC and scrubbing policies, versioning is configured **per-server only** and is not part of the 3-layer policy hierarchy.
When enabled on a server, new or modified capabilities require admin approval before becoming active:
1. Gateway discovers new/changed capabilities during refresh
2. Changes are marked as "pending approval"
3. Capabilities are blocked until an admin approves them
4. All changes are recorded in the capability history for audit
For step-by-step setup, see [Configure Server RBAC](/gateway/guides/security/setup-server-rbac), [Configure Capability RBAC](/gateway/guides/security/setup-capability-rbac), and [Configure PII Scrubbing](/gateway/guides/security/configure-pii-scrubbing).
## Authentication
Golf Gateway implements a **proxy authentication model**: users authenticate to the gateway once, and the gateway manages credentials for upstream MCP servers.
**How It Works**
1. **User authenticates to Gateway** via your identity provider (Auth0, Entra ID, Descope)
2. **Gateway issues a session token** (HS256 JWT) for subsequent requests
3. **Gateway injects upstream credentials** for each MCP server the user accesses
4. **Users never see upstream credentials** - they're managed entirely by the gateway
**Credential Types**
Golf supports two types of upstream credentials:
For MCP servers that accept static API keys:
1. User provides their API key once in the Dev Portal
2. Key is encrypted and stored securely
3. Gateway injects the key into requests automatically
**Use case**: Internal APIs, services with static authentication
For third-party services requiring OAuth:
1. User authorizes the service once via OAuth flow
2. Gateway stores encrypted access + refresh tokens
3. Gateway automatically refreshes expired tokens
**Use case**: GitHub, Slack, Notion, other OAuth-enabled services
**Security Benefits**
Golf Gateway's credential management provides several important security benefits. First, credential isolation ensures that users never see or handle raw API keys or OAuth tokens; all sensitive credentials are stored and managed by the gateway itself. The system also supports automatic refresh of OAuth tokens, so users maintain access without manual intervention or interruptions.
Centralized revocation gives administrators the ability to disable access instantly by removing credentials from the gateway, eliminating the risk of lingering permissions. Additionally, Golf Gateway maintains a complete audit trail—every time credentials are used, that activity is securely logged, enabling compliance, oversight, and incident response.
## Configuration Modes
Golf Gateway supports two primary configuration modes that determine where configuration and policies are loaded from:
**All configuration from Control Plane**
```mermaid theme={null}
flowchart LR
A["Control Plane"] --> B["Gateway"]
style A fill:#6366f1,stroke:#4f46e5,color:#ffffff
```
* MCP servers, policies, and exporters defined in Control Plane UI
* Gateway fetches configuration bundles on startup and heartbeat
* Hot reload on configuration changes (no restart needed)
**Best for**: Teams wanting full UI-based management, multi-gateway deployments
**Local YAML + Control Plane policies**
```mermaid theme={null}
flowchart LR
A["YAML File"] --> B["Gateway"]
C["Control Plane"] -.->|"policies only"| B
style C fill:#6366f1,stroke:#4f46e5,color:#ffffff
```
* MCP servers and gateway config defined in local YAML file
* Organization-wide policies fetched from Control Plane
* YAML changes hot-reloaded via file watcher
**Best for**: GitOps workflows, infrastructure-as-code teams
**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 |
These modes are not mutually exclusive. You can run some gateways in centralized mode and others in distributed mode within the same organization. All gateways share organization-wide policies from the Control Plane.
**Mode Detection**
Golf Gateway automatically detects which mode to use:
1. **YAML file with `control_plane` section** → Distributed mode
2. **Control Plane environment variables only (no YAML)** → Centralized mode
No explicit mode configuration is required.
**Hot Reload**
Both modes support hot reload without gateway restart:
| Mode | Trigger | Latency |
| ----------- | ---------------------------------- | ------------ |
| Centralized | Config version change on heartbeat | \~30 seconds |
| Distributed | File system change detected | \~1 second |
For deployment guides, see [Deploy Centralized](/gateway/guides/getting-started/deploy-control-plane) and [Deploy Distributed](/gateway/guides/getting-started/deploy-hybrid-mode).
## When to Deploy Multiple Gateways
Just as organizations deploy multiple API gateways for different domains and audiences, Golf Gateway supports multi-gateway architectures. Each gateway can serve a specific purpose while reporting to the same Control Plane for unified visibility.
**Separate gateways for different business domains**
Each team or department gets its own gateway with tailored policies:
* **Engineering Gateway** - Company-built agents accessing internal APIs
* **HR Gateway** - Employee-facing agents with strict PII controls
* **Finance Gateway** - Agents accessing financial systems with enhanced audit requirements
**Benefits**: Teams manage their own configurations. Domain-specific security policies. Clear ownership boundaries.
**Different gateways for different user populations**
Separate internal users from external access:
* **Internal Gateway** - Employees accessing all approved MCP servers
* **Partner Gateway** - External partners with limited server access
* **Public Gateway** - Public-facing MCP servers with strict rate limits
**Benefits**: Different trust levels. Tailored rate limits. Isolated blast radius if one gateway is compromised.
**Isolated gateways per deployment environment**
Standard environment separation:
* **Development Gateway** - Relaxed policies for testing
* **Staging Gateway** - Production-like policies for validation
* **Production Gateway** - Full security controls enabled
**Benefits**: Safe testing without affecting production. Gradual policy rollout. Environment-specific MCP servers.
### Benefits
| Benefit | Description |
| -------------------------- | ---------------------------------------------------------------------- |
| **Blast Radius Isolation** | Issues in one gateway don't affect others |
| **Tailored Policies** | Different security requirements per domain or audience |
| **Independent Scaling** | Scale high-traffic gateways without over-provisioning others |
| **Team Autonomy** | Teams can manage their own gateway configuration (in Distributed mode) |
| **Unified Visibility** | Single Control Plane for cross-gateway analytics and audit |
Start with a single gateway and add more as your requirements grow. The Control Plane makes it easy to manage any number of gateways from one place.
## Deployment
Golf Gateway is available as Docker images optimized for different hardware configurations.
### Image Variants
| Variant | Tag | Size | Hardware | Use Case |
| ------- | ------------ | -------- | ---------- | --------------------------------------------------------- |
| Default | `v1.0.0` | \~1.5 GB | CPU only | Production deployments using remote threat detection |
| GPU | `v1.0.0-gpu` | \~8 GB | NVIDIA GPU | Production with local ML inference and advanced PII needs |
The default image is a lightweight build (\~1.5 GB) that offloads threat detection to a remote endpoint. The GPU image bundles all ML models locally for self-contained inference.
### Choosing the Right Image
**Best for: Most production deployments**
* \~1.5 GB image — fast pull and startup
* Threat detection offloaded to a remote endpoint (e.g., Azure ML)
* Works on any infrastructure without special hardware
* Requires `security.llm.backend: remote` in YAML (or `GOLF_SECURITY_LLM_BACKEND=remote`)
**When to use**:
* Production deployments with a dedicated inference endpoint
* Environments with bandwidth or storage constraints
* Teams that manage their own ML infrastructure
* Quick testing and evaluation
**Best for: Self-contained deployments with local ML inference**
* All default image capabilities, plus:
* Local LLM threat detection (no remote endpoint needed)
* Hardware-accelerated ML inference
**When to use**:
* Environments without external inference endpoints
* Production with high throughput requirements
**Performance**: Significantly higher throughput for ML-intensive workloads
### Hardware Requirements
**Recommended**:
* 4 vCPU
* 8 GB RAM
**AWS example**: `c7a.xlarge`
The default image is lightweight and does not run local ML models, so hardware requirements are minimal.
**MVP / Initial deployment**:
* NVIDIA T4 GPU (CUDA 12.4 support)
* 4 vCPU
* 16 GB RAM
* AWS example: `g4dn.xlarge`
**Full production rollout**:
* NVIDIA A10G or L4 GPU
* 8+ vCPU
* 32 GB RAM
* AWS example: `g5.2xlarge` (1x A10G, 8 vCPU, 32 GB RAM)
### Required Dependencies
Golf Gateway requires the following external services:
| Service | Purpose | Notes |
| --------- | ------------------------------------------------------------------------ | -------------------------------- |
| **Redis** | Session management, rate limiting, replay protection, auth token caching | Required. Redis 7.x recommended. |
Redis is essential for Golf Gateway operation.
### Container Orchestration
Golf can provide example Helm charts for Kubernetes deployments. Contact the Golf team for access to deployment templates and configuration examples tailored to your infrastructure.
For production deployment configuration, see [Environment Variables Reference](/gateway/reference/environment-variables) and [YAML Schema](/gateway/reference/yaml-schema).