GolfMCP provides flexible authentication mechanisms to secure your MCP servers:
  1. JWT Authentication - Enterprise-grade authentication with JWKS support for production
  2. Development Authentication - Simple token-based authentication for development and testing
  3. OAuth Server - Full OAuth 2.0 authorization server functionality
  4. Remote Authentication - Distributed authentication across multiple resource servers
  5. 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

  1. Token Validation: Golf validates JWTs against the JWKS endpoint
  2. Standards Compliance: Full RFC 7519 JWT validation
  3. 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
)

​
Using API Keys in Tools

Tools access the API key with a simple import: 
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}"}
    )

​
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
    )
)