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.
Let’s get you started with your first GolfMCP project from scratch.
Install GolfMCP
Install the Golf MCP framework using pip: Initialize your project
Create a new GolfMCP project using the init command:golf init my_awesome_server
cd my_awesome_server
my_awesome_server with the following structure:my_awesome_server/
├── golf.json # Main project configuration
├── auth.py # Authentication configuration (new in v0.2.0)
├── prompts/ # Directory for prompt components
│ └── welcome.py
├── resources/ # Directory for resource components
│ ├── current_time.py
│ └── info.py
│ └── weather/
│ ├── common.py
│ ├── current.py
│ └── forecast.py
└── tools/ # Directory for tool components
├── github_user.py
├── hello.py
└── payments/
├── charge.py
├── common.py
└── refund.py
golf.json: Configures your server’s name, port, transport, etc. (see Configuration)auth.py: Dedicated file for authentication setup (see Authentication)tools/, resources/, prompts/: Directories where you’ll define your server’s capabilities (see Component Specification)
Set up authentication
The boilerplate example includes a tool that requires authentication. Golf v0.2.0 offers three authentication methods (for complete details, see Authentication):
-
Configure API key authentication in
auth.py:
from golf.auth import configure_api_key
# Extract API key from Authorization header
configure_api_key(
header_name="Authorization",
header_prefix="Bearer "
)
-
Pass the token when connecting your MCP client
-
Access the API key in your tools using:
from golf.auth import get_api_key
api_key = get_api_key()
-
Configure development tokens in
auth.py:
from golf.auth import configure_auth, StaticTokenConfig
configure_auth(
StaticTokenConfig(
tokens={
"dev-token-123": {
"client_id": "dev-client",
"scopes": ["read", "write"]
}
},
required_scopes=["read"]
)
)
-
Use the development token when connecting:
# Pass token via Authorization header
Authorization: Bearer dev-token-123
-
No additional setup required - perfect for development and testing
-
Set up your JWT provider (Auth0, Okta, etc.)
-
Configure JWT authentication in
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"]
)
)
-
Set environment variables:
JWKS_URI=https://your-provider.com/.well-known/jwks.json
JWT_ISSUER=https://your-provider.com/
JWT_AUDIENCE=your-api-audience
-
Enterprise-grade security with standards-compliant JWT validation
Create your first tool
Let’s modify the example “hello” tool. Open tools/hello.py:"""Hello World tool for {{project_name}}."""
from typing import Annotated
from pydantic import BaseModel, Field
class Output(BaseModel):
"""Response from the hello tool."""
message: str
async def hello(
name: Annotated[str, Field(description="The name of the person to greet")] = "World",
greeting: Annotated[str, Field(description="The greeting phrase to use")] = "Hello"
) -> Output:
"""Say hello to the given name.
This is a simple example tool that demonstrates the basic structure
of a tool implementation in GolfMCP.
"""
# The framework will add a context object automatically
# You can log using regular print during development
print(f"{greeting} {name}...")
# Create and return the response
return Output(message=f"{greeting}, {name}!")
# Designate the entry point function
export = hello
Build for development
Compile your project for development:This command builds the actual MCP server. Run your server
Execute the built server:Congratulations! You’ve built and run your first GolfMCP server. Next Steps
Now that you have a working MCP server, learn how to test it comprehensively:
