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.
GolfMCP provides flexible authentication mechanisms to secure your MCP servers:
- JWT Authentication - Enterprise-grade authentication with JWKS support for production
- Development Authentication - Simple token-based authentication for development and testing
- OAuth Server - Full OAuth 2.0 authorization server functionality
- Remote Authentication - Distributed authentication across multiple resource servers
- API Key Authentication - Pass-through authentication to upstream APIs
Authentication is configured using a dedicated auth.py file in your project root, providing clean separation from other build logic.
JWT authentication
Overview
JWT authentication provides enterprise-grade security with JWKS (JSON Web Key Set) support. This is the recommended approach for production environments where you need standards-compliant token validation.
Configuration
Configure JWT authentication in your project’s auth.py:
# auth.py
from golf.auth import configure_auth, JWTAuthConfig
configure_auth(
JWTAuthConfig(
jwks_uri_env_var="JWKS_URI",
issuer_env_var="JWT_ISSUER",
audience_env_var="JWT_AUDIENCE",
required_scopes=["read:user"]
)
)
Environment variables
Set these environment variables in your .env file:
JWKS_URI=https://your-provider.com/.well-known/jwks.json
JWT_ISSUER=https://your-provider.com/
JWT_AUDIENCE=your-api-audience
# Alternative: PEM-encoded public key (instead of JWKS_URI)
JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEF..."
# Multiple audiences (comma-separated)
JWT_AUDIENCE=https://api.production.com,https://api2.production.com
How it works
- Token Validation: Golf validates JWTs against the JWKS endpoint
- Standards Compliance: Full RFC 7519 JWT validation
- Scope Verification: Ensures tokens have required scopes
Development authentication
Overview
Development authentication provides a simple token-based system perfect for development and testing environments. You can define custom tokens with specific client IDs and scopes.
Configuration
Configure development authentication in your project’s auth.py:
# auth.py
from golf.auth import configure_auth, StaticTokenConfig
configure_auth(
StaticTokenConfig(
tokens={
"dev-token-123": {
"client_id": "dev-client",
"scopes": ["read", "write"]
},
"test-token-456": {
"client_id": "test-client",
"scopes": ["read"]
}
},
required_scopes=["read"]
)
)
Using development tokens
Pass tokens via the Authorization header:
curl -H "Authorization: Bearer dev-token-123" http://localhost:3000/mcp
OAuth server configuration
Overview
Golf v0.2.0 can act as a complete OAuth 2.0 authorization server, not just validate tokens. This mode allows your MCP server to issue JWT tokens to clients and provide full OAuth 2.0 endpoints for authorization, token issuance, and revocation.
Configuration
Configure OAuth server mode in your project’s auth.py:
# auth.py
from golf.auth import configure_auth, OAuthServerConfig
configure_auth(
OAuthServerConfig(
base_url="https://auth.example.com", # Public URL of your server
issuer_url="https://auth.example.com", # OAuth issuer URL
service_documentation_url="https://docs.example.com", # Optional
# Scope configuration
valid_scopes=["read", "write", "admin"], # Scopes clients can request
default_scopes=["read"], # Default scopes for new clients
required_scopes=["read"], # Scopes required for all requests
# Environment variable support
base_url_env_var="OAUTH_BASE_URL" # Runtime URL override
)
)
Environment variables
Configure runtime URL overrides in your .env file:
# .env file
OAUTH_BASE_URL=https://auth.production.com
Remote authentication configuration
Overview
Remote authentication allows you to distribute authentication across multiple resource servers while maintaining centralized token validation. This is useful for microservices architectures where multiple services need to validate tokens from the same authorization servers.
Configuration
# auth.py
from golf.auth import configure_auth, RemoteAuthConfig, JWTAuthConfig
configure_auth(
RemoteAuthConfig(
# Static configuration
authorization_servers=["https://auth1.example.com"],
resource_server_url="https://api.example.com",
# Environment variable resolution (NEW in v0.2.0)
authorization_servers_env_var="AUTH_SERVERS", # Comma-separated server URLs
resource_server_url_env_var="RESOURCE_URL", # This resource server's URL
token_verifier_config=JWTAuthConfig(jwks_uri_env_var="JWKS_URI")
)
)
Environment variables
# .env file for Remote Auth
AUTH_SERVERS=https://auth1.prod.com,https://auth2.prod.com,https://backup-auth.prod.com
RESOURCE_URL=https://api.production.com
JWKS_URI=https://auth1.prod.com/.well-known/jwks.json
API key authentication
Overview
Golf provides a simple API key pass-through authentication mechanism that allows MCP servers to extract API keys from request headers and forward them to upstream services. The actual authentication happens at the destination API level, not within the MCP server.
Configuration
Configure API key extraction in your project’s auth.py:
# auth.py
from golf.auth import configure_api_key
# Configure which header contains the API key
configure_api_key(
header_name="Authorization", # Header to extract from
header_prefix="Bearer " # Optional prefix to strip
)
from golf.auth import get_api_key
async def my_tool():
api_key = get_api_key()
if not api_key:
return {"error": "No API key provided"}
# Use the key with your API
response = await client.get(
"https://api.example.com/endpoint",
headers={"Authorization": f"Bearer {api_key}"}
)
Overview
Golf provides a utility function for extracting authentication tokens from reqest context within your MCP tools: get_auth_token().
get_auth_token()
from golf.auth import get_auth_token
async def secure_api_tool(data: str):
# Extract authentication token
auth_token = get_auth_token()
if not auth_token:
return {"error": "JWT/OAuth token required"}
# Forward token to upstream API
import httpx
async with httpx.AsyncClient() as client:
response = await client.post(
"https://api.example.com/secure-endpoint",
headers={"Authorization": f"Bearer {auth_token}"},
json={"data": data}
)
return {
"data": data,
"response": response.json(),
"authenticated": True
}
Enhanced environment variable support
Overview
Golf v0.2.0 significantly expanded environment variable support across all auth providers.
JWT authentication environment variables
All JWT fields now support environment variable resolution:
# All JWT fields now support environment variables
configure_auth(
JWTAuthConfig(
# Direct values (still supported)
jwks_uri="https://auth.example.com/.well-known/jwks.json",
# Environment variable resolution (preferred for deployment)
public_key_env_var="JWT_PUBLIC_KEY", # PEM-encoded public key
jwks_uri_env_var="JWKS_URI", # JWKS endpoint URL
issuer_env_var="JWT_ISSUER", # Expected issuer
audience_env_var="JWT_AUDIENCE", # Expected audience(s)
required_scopes=["read:user"] # Scopes are part of the config object
)
)
Migration from v0.1.x
Breaking changes from previous versions:
# ❌ BROKEN - These will cause TypeError in v0.2.0
configure_jwt_auth(
jwks_uri_env_var="JWKS_URI",
required_scopes=["read:user"] # This parameter was removed
)
configure_dev_auth(
tokens={"dev-token": {"client_id": "dev"}},
required_scopes=["read"] # This parameter was removed
)
# ✅ CORRECT - v0.2.0 syntax
from golf.auth import configure_auth, JWTAuthConfig, StaticTokenConfig
# JWT Auth - scopes are part of the config object
configure_auth(
JWTAuthConfig(
jwks_uri_env_var="JWKS_URI",
required_scopes=["read:user"] # Scopes are part of the config object
)
)
# Development Auth
configure_auth(
StaticTokenConfig(
tokens={
"dev-token-123": {
"client_id": "dev-client",
"scopes": ["read", "write"]
}
},
required_scopes=["read"] # Scopes are part of the config object
)
)
