Let’s get you started with your first GolfMCP project from scratch.
1

Install GolfMCP

Install the Golf MCP framework using pip:
pip install golf-mcp
2

Initialize your project

Create a new GolfMCP project using the init command:
golf init my_awesome_server
cd my_awesome_server
This will create a new directory named 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)
3

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):
  1. 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 "
)
  2. Pass the token when connecting your MCP client
  3. Access the API key in your tools using: 
    from golf.auth import get_api_key

api_key = get_api_key()
4

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
For more details on tool structure, parameters, and advanced patterns, see the Component Specification.
5

Build for development

Compile your project for development:
golf build dev
This command builds the actual MCP server.
6

Run your server

Execute the built server:
golf run
Congratulations! You’ve built and run your first GolfMCP server.