Golf

<div align="center">

<img src="./golf-banner.png" alt="Golf Banner">

<br>

<h1 align="center">

<br>

<span style="font-size: 80px;">⛳ Golf</span>

<br>

</h1>

<h3 align="center">

Easiest framework for building MCP servers

</h3>

<br>

<p>

<a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a>

<a href="https://github.com/golf-mcp/golf/pulls"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs"></a>

<a href="https://github.com/golf-mcp/golf/issues"><img src="https://img.shields.io/badge/support-contact%20author-purple.svg" alt="Support"></a>

</p>

<p>

<a href="https://docs.golf.dev"><strong>📚 Documentation</strong></a>

</p>

</div>

Overview

Golf is a framework designed to streamline the creation of MCP server applications. It allows developers to define server's capabilities—tools, prompts, and resources—as simple Python files within a conventional directory structure. Golf then automatically discovers, parses, and compiles these components into a runnable MCP server, minimizing boilerplate and accelerating development.

Golf targets FastMCP 4.0.0 and the current MCP 2026-07-28 protocol.

FastMCP also negotiates legacy MCP clients through its compatibility mode.

With Golf v0.2.0, you get enterprise-grade authentication (JWT, OAuth Server, development tokens), built-in utilities for LLM interactions, and automatic telemetry integration. Focus on implementing your agent's logic while Golf handles authentication, monitoring, and server infrastructure.

Quick Start

Get your Golf project up and running in a few simple steps:

1. Install Golf

Golf requires Python 3.10 or newer. Then, install Golf using pip:

pip install golf-mcp

2. Initialize Your Project

Use the Golf CLI to scaffold a new project:

golf init your-project-name

This command creates a new directory (your-project-name) with a basic project structure, including example tools, resources, and a golf.json configuration file.

3. Run the Development Server

Navigate into your new project directory and start the development server:

cd your-project-name
golf build dev
golf run

This will start the MCP server, typically on http://localhost:3000 (configurable in golf.json).

That's it! Your Golf server is running and ready for integration.

Basic Project Structure

A Golf project initialized with golf init will have a structure similar to this:

<your-project-name>/
│
├─ golf.json          # Main project configuration
│
├─ tools/             # Directory for tool implementations
│   └─ hello.py       # Example tool
│
├─ resources/         # Directory for resource implementations
│   └─ info.py        # Example resource
│
├─ prompts/           # Directory for prompt templates
│   └─ welcome.py     # Example prompt
│
├─ .env               # Environment variables (e.g., API keys, server port)
└─ auth.py            # Authentication configuration (JWT, OAuth Server, API key, dev tokens)

• `golf.json`: Configures server name, port, transport, telemetry, and other build settings.
• `auth.py`: Dedicated authentication configuration file (new in v0.2.0, breaking change from v0.1.x authentication API) for JWT, OAuth Server, API key, or development authentication.
• `tools/`, `resources/`, `prompts/`: Contain your Python files, each defining a single component. These directories can also contain nested subdirectories to further organize your components (e.g., tools/payments/charge.py). The module docstring of each file serves as the component's description.

- Component IDs are automatically derived from their file path. For example, tools/hello.py becomes hello, and a nested file like tools/payments/submit.py would become submit_payments (filename, followed by reversed parent directories under the main category, joined by underscores).

Example: Defining a Tool

Creating a new tool is as simple as adding a Python file to the tools/ directory. The example tools/hello.py in the boilerplate looks like this:

# tools/hello.py
"""Hello World tool {{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 Golf.
    """
    print(f"{greeting} {name}...")
    return Output(message=f"{greeting}, {name}!")

# Designate the entry point function
export = hello

Golf will automatically discover this file. The module docstring """Hello World tool {{project_name}}.""" is used as the tool's description. It infers parameters from the hello function's signature and uses the Output Pydantic model for the output schema. The tool will be registered with the ID hello.

Authentication & Features

Golf includes enterprise-grade authentication, built-in utilities, and automatic telemetry:

# auth.py - Configure authentication
from golf.auth import configure_auth, JWTAuthConfig, StaticTokenConfig, OAuthServerConfig

# JWT authentication (production)
configure_auth(JWTAuthConfig(
    jwks_uri_env_var="JWKS_URI",
    issuer_env_var="JWT_ISSUER", 
    audience_env_var="JWT_AUDIENCE",
    required_scopes=["read", "write"]
))

# OAuth Server mode (Golf acts as OAuth 2.0 server)
# configure_auth(OAuthServerConfig(
#     base_url="https://your-golf-server.com",
#     valid_scopes=["read", "write", "admin"]
# ))

# Static tokens (development only)
# configure_auth(StaticTokenConfig(
#     tokens={"dev-token": {"client_id": "dev", "scopes": ["read"]}}
# ))

# Built-in utilities available in all tools
from golf.utilities import elicit, sample, get_current_context

On MCP 2026-07-28, elicitation and sampling use caller-owned multi-round-trip

control flow. A nested helper cannot transparently continue the containing

tool: declare InputRequiredResult in the tool's return type and return any

such result unchanged. The tool is then re-entered with the answer. Legacy

connections continue to use imperative requests.

from mcp_types import InputRequiredResult
from golf.utilities import sample

async def explain(topic: str) -> str | InputRequiredResult:
    result = await sample(f"Explain {topic}")
    if isinstance(result, InputRequiredResult):
        return result
    return result

JWT authentication requires an audience so tokens are bound to this MCP

resource. Inbound MCP JWT/OAuth bearer tokens must never be forwarded to an

upstream API; use a separate upstream credential or a standards-based token

exchange/delegation flow.

# Enable OpenTelemetry tracing
export OTEL_TRACES_EXPORTER="otlp_http"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318/v1/traces"
golf run  # ✅ Telemetry enabled

[📚 Complete Documentation →](https://docs.golf.dev)

Configuration

Basic configuration in golf.json:

{
  "name": "My Golf Server",
  "host": "localhost",
  "port": 3000,
  "transport": "streamable-http",
  "opentelemetry_enabled": false,
  "detailed_tracing": false
}

• `transport`: Use "streamable-http" or "stdio". SSE remains available

only as a deprecated legacy transport.

• **stateless_http**: Optional legacy Streamable HTTP behavior. MCP

2026-07-28 is intrinsically sessionless and does not depend on this setting.

• **opentelemetry_enabled**: Enable OpenTelemetry tracing
• **detailed_tracing**: Capture input/output (use carefully with sensitive data)

Privacy & Telemetry

Golf collects anonymous usage data on the CLI to help us understand how the framework is being used and improve it over time. The data collected includes:

• Commands run (init, build, run)
• Success/failure status (no error details)
• Golf version, Python version (major.minor only), and OS type
• Template name (for init command only)
• Build environment (dev/prod for build commands only)

No personal information, project names, code content, or error messages are ever collected.

Opting Out

You can disable telemetry in several ways:

1. Using the telemetry command (recommended):

```bash

golf telemetry disable

```

This saves your preference permanently. To re-enable:

```bash

golf telemetry enable

```

1. During any command: Add --no-telemetry to save your preference:

```bash

golf init my-project --no-telemetry

```

Your telemetry preference is stored in ~/.golf/telemetry.json and persists across all Golf commands.

<div align="center">

Made with ❤️ in Warsaw, Poland and SF

</div>