GolfMCP quickstart

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

Install GolfMCP

Install the Golf MCP framework using pip:

pip install golf-mcp

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)

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

API key authentication
Development authentication
JWT authentication (Production)

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

For more details on tool structure, parameters, and advanced patterns, see the Component Specification.

Build for development

Compile your project for development:

golf build dev

This command builds the actual MCP server.

Run your server

Execute the built server:

golf run

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:

Test your server - Use mcp-t to validate your implementation
Set up automated testing - Create test suites for CI/CD
Learn testing philosophy - Understand why traditional testing fails for MCP

Getting started

Core concepts

Authentication

Advanced features

Reference

Next Steps

​Next Steps

Next Steps