Skip to main content
GolfMCP uses a convention-based project structure. 
<project-root>/
├── golf.json
├── auth.py               # Authentication configuration (v0.2.0)
├── startup.py            # Optional initialization script (v0.2.10)
├── health.py             # Optional health check endpoint (v0.2.11)
├── readiness.py          # Optional readiness check endpoint (v0.2.11)
├── prompts/
│   └── example_prompt.py
├── resources/
│   └── example_resource.py
│   └── sub_category/
│       └── nested_resource.py
│       └── common.py
└── tools/
    └── example_tool.py
    └── payments/
        └── common.py
        └── get_balance.py
        └── transaction/
            └── submit.py
  • golf.json: The main configuration file (see Configuration).
  • auth.py: Dedicated authentication configuration file (see Authentication).
  • startup.py: Optional initialization script for environment setup and server startup configuration.
  • health.py: Optional custom health check endpoint with sophisticated monitoring logic (see Telemetry & Monitoring).
  • readiness.py: Optional custom readiness check endpoint for Kubernetes-style probes (see Telemetry & Monitoring).
  • tools/: Contains Python files defining your server’s tools (see Component Specification).
  • resources/: Contains Python files defining data resources the LLM can read (see Component Specification).
  • prompts/: Contains Python files defining reusable prompt templates (see Component Specification).
Deprecated: Authentication configuration in pre_build.py is deprecated. Use the dedicated auth.py file instead for cleaner organization and better maintainability.

​
Component discovery

  • Each .py file within tools/, resources/, or prompts/ (and their subdirectories) is treated as a single component.
  • Files named __init__.py are ignored for direct component definition but are essential for Python’s packaging if you structure your components as modules.
  • Files named common.py are special and used for shared code (see Shared Logic documentation).
  • The auth.py file is treated specially for authentication configuration and is not considered a component.
  • The startup.py file is treated specially for server initialization and is not considered a component.
  • The health.py and readiness.py files are treated specially for health check endpoints and are not considered components.

​
Component ID derivation

The unique ID for each component is derived from its file path relative to the category directory (tools, resources, prompts). Examples:
  • tools/hello.py -> ID: hello
  • tools/payments/transaction/submit.py -> ID: submit-transaction-payments
  • resources/weather/current.py -> ID: current-weather
ID collisions will result in a build-time error.

​
Authentication configuration

​
The auth.py file (new in v0.2.0)

Golf v0.2.0 introduces a dedicated auth.py file for authentication configuration, providing better organization and cleaner separation from other build logic. Example auth.py configurations (for full details, see Authentication): 
# auth.py - API Key Authentication
from golf.auth import configure_api_key

configure_api_key(
    header_name="Authorization",
    header_prefix="Bearer "
)

# auth.py - JWT Authentication
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"]
    )
)

# auth.py - Development Authentication
from golf.auth import configure_auth, StaticTokenConfig

configure_auth(
    StaticTokenConfig(
        tokens={
            "dev-token-123": {
                "client_id": "dev-client",
                "scopes": ["read", "write"]
            }
        },
        required_scopes=["read"]
    )
)

​
Runtime initialization

​
The startup.py file (optional)

The startup.py file is an optional initialization script that allows projects to execute custom code before the FastMCP server starts. It’s designed for setting environment variables, loading secrets, and performing project-specific setup. Key characteristics:
  • Optional: Projects work without it
  • Runtime execution: Runs when the server starts, not during build
  • Environment focused: Primarily used for secrets, API keys, and configuration

​
Core implementation

The startup script functionality is automatically detected during build and executed at server runtime with robust error handling.

​
Common usage patterns

Basic Environment Setup: 
# startup.py
import os

os.environ.setdefault("GOLF_DEBUG", "true")
os.environ["DATABASE_URL"] = "sqlite:///app.db"
print("Startup script executed successfully")
API Key and Secrets Loading: 
# startup.py
import os

# Configure API keys
os.environ["OPENAI_API_KEY"] = "test-openai-key"
os.environ["ANTHROPIC_API_KEY"] = "test-anthropic-key"

print("Environment configured successfully")
⌘I