Skip to content
Back to search

golf

Production-Ready MCP Server Framework • Build, deploy & scale secure AI agent infrastructure • Includes Auth, Observability, Debugger, Telemetry & Runtime • Run real-world MCPs powering AI Agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/golf-mcp--golf/badge.svg)](/listings/golf-mcp--golf)

HTML

<a href="/listings/golf-mcp--golf"><img src="/api/listings/golf-mcp--golf/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 250 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="./golf-banner.png" alt="Golf Banner">
  3. <br>
  4. <h1 align="center">
  5. <br>
  6. <span style="font-size: 80px;">⛳ Golf</span>
  7. <br>
  8. </h1>
  9. <h3 align="center">
  10. Easiest framework for building MCP servers
  11. </h3>
  12. <br>
  13. <p>
  14. <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>
  15. <a href="https://github.com/golf-mcp/golf/pulls"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs"></a>
  16. <a href="https://github.com/golf-mcp/golf/issues"><img src="https://img.shields.io/badge/support-contact%20author-purple.svg" alt="Support"></a>
  17. </p>
  18. <p>
  19. <a href="https://docs.golf.dev"><strong>📚 Documentation</strong></a>
  20. </p>
  21. </div>
  22. ## Overview
  23. 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.
  24. Golf targets FastMCP 4.0.0 and the current MCP 2026-07-28 protocol.
  25. FastMCP also negotiates legacy MCP clients through its compatibility mode.
  26. 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.
  27. ## Quick Start
  28. Get your Golf project up and running in a few simple steps:
  29. ### 1. Install Golf
  30. Golf requires Python 3.10 or newer. Then, install Golf using pip:
  31. ```bash
  32. pip install golf-mcp
  33. ```
  34. ### 2. Initialize Your Project
  35. Use the Golf CLI to scaffold a new project:
  36. ```bash
  37. golf init your-project-name
  38. ```
  39. This command creates a new directory (`your-project-name`) with a basic project structure, including example tools, resources, and a `golf.json` configuration file.
  40. ### 3. Run the Development Server
  41. Navigate into your new project directory and start the development server:
  42. ```bash
  43. cd your-project-name
  44. golf build dev
  45. golf run
  46. ```
  47. This will start the MCP server, typically on `http://localhost:3000` (configurable in `golf.json`).
  48. That's it! Your Golf server is running and ready for integration.
  49. ## Basic Project Structure
  50. A Golf project initialized with `golf init` will have a structure similar to this:
  51. ```
  52. <your-project-name>/
  53. │
  54. ├─ golf.json # Main project configuration
  55. │
  56. ├─ tools/ # Directory for tool implementations
  57. │ └─ hello.py # Example tool
  58. │
  59. ├─ resources/ # Directory for resource implementations
  60. │ └─ info.py # Example resource
  61. │
  62. ├─ prompts/ # Directory for prompt templates
  63. │ └─ welcome.py # Example prompt
  64. │
  65. ├─ .env # Environment variables (e.g., API keys, server port)
  66. └─ auth.py # Authentication configuration (JWT, OAuth Server, API key, dev tokens)
  67. ```
  68. - **`golf.json`**: Configures server name, port, transport, telemetry, and other build settings.
  69. - **`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.
  70. - **`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.
  71. - 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).
  72. ## Example: Defining a Tool
  73. 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:
  74. ```python
  75. # tools/hello.py
  76. """Hello World tool {{project_name}}."""
  77. from typing import Annotated
  78. from pydantic import BaseModel, Field
  79. class Output(BaseModel):
  80. """Response from the hello tool."""
  81. message: str
  82. async def hello(
  83. name: Annotated[str, Field(description="The name of the person to greet")] = "World",
  84. greeting: Annotated[str, Field(description="The greeting phrase to use")] = "Hello"
  85. ) -> Output:
  86. """Say hello to the given name.
  87. This is a simple example tool that demonstrates the basic structure
  88. of a tool implementation in Golf.
  89. """
  90. print(f"{greeting} {name}...")
  91. return Output(message=f"{greeting}, {name}!")
  92. # Designate the entry point function
  93. export = hello
  94. ```
  95. 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`.
  96. ## Authentication & Features
  97. Golf includes enterprise-grade authentication, built-in utilities, and automatic telemetry:
  98. ```python
  99. # auth.py - Configure authentication
  100. from golf.auth import configure_auth, JWTAuthConfig, StaticTokenConfig, OAuthServerConfig
  101. # JWT authentication (production)
  102. configure_auth(JWTAuthConfig(
  103. jwks_uri_env_var="JWKS_URI",
  104. issuer_env_var="JWT_ISSUER",
  105. audience_env_var="JWT_AUDIENCE",
  106. required_scopes=["read", "write"]
  107. ))
  108. # OAuth Server mode (Golf acts as OAuth 2.0 server)
  109. # configure_auth(OAuthServerConfig(
  110. # base_url="https://your-golf-server.com",
  111. # valid_scopes=["read", "write", "admin"]
  112. # ))
  113. # Static tokens (development only)
  114. # configure_auth(StaticTokenConfig(
  115. # tokens={"dev-token": {"client_id": "dev", "scopes": ["read"]}}
  116. # ))
  117. # Built-in utilities available in all tools
  118. from golf.utilities import elicit, sample, get_current_context
  119. ```
  120. On MCP 2026-07-28, elicitation and sampling use caller-owned multi-round-trip
  121. control flow. A nested helper cannot transparently continue the containing
  122. tool: declare `InputRequiredResult` in the tool's return type and return any
  123. such result unchanged. The tool is then re-entered with the answer. Legacy
  124. connections continue to use imperative requests.
  125. ```python
  126. from mcp_types import InputRequiredResult
  127. from golf.utilities import sample
  128. async def explain(topic: str) -> str | InputRequiredResult:
  129. result = await sample(f"Explain {topic}")
  130. if isinstance(result, InputRequiredResult):
  131. return result
  132. return result
  133. ```
  134. JWT authentication requires an audience so tokens are bound to this MCP
  135. resource. Inbound MCP JWT/OAuth bearer tokens must never be forwarded to an
  136. upstream API; use a separate upstream credential or a standards-based token
  137. exchange/delegation flow.
  138. ```bash
  139. # Enable OpenTelemetry tracing
  140. export OTEL_TRACES_EXPORTER="otlp_http"
  141. export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318/v1/traces"
  142. golf run # ✅ Telemetry enabled
  143. ```
  144. **[📚 Complete Documentation →](https://docs.golf.dev)**
  145. ## Configuration
  146. Basic configuration in `golf.json`:
  147. ```json
  148. {
  149. "name": "My Golf Server",
  150. "host": "localhost",
  151. "port": 3000,
  152. "transport": "streamable-http",
  153. "opentelemetry_enabled": false,
  154. "detailed_tracing": false
  155. }
  156. ```
  157. - **`transport`**: Use `"streamable-http"` or `"stdio"`. SSE remains available
  158. only as a deprecated legacy transport.
  159. - **`stateless_http`**: Optional legacy Streamable HTTP behavior. MCP
  160. 2026-07-28 is intrinsically sessionless and does not depend on this setting.
  161. - **`opentelemetry_enabled`**: Enable OpenTelemetry tracing
  162. - **`detailed_tracing`**: Capture input/output (use carefully with sensitive data)
  163. ## Privacy & Telemetry
  164. 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:
  165. - Commands run (init, build, run)
  166. - Success/failure status (no error details)
  167. - Golf version, Python version (major.minor only), and OS type
  168. - Template name (for init command only)
  169. - Build environment (dev/prod for build commands only)
  170. **No personal information, project names, code content, or error messages are ever collected.**
  171. ### Opting Out
  172. You can disable telemetry in several ways:
  173. 1. **Using the telemetry command** (recommended):
  174. ```bash
  175. golf telemetry disable
  176. ```
  177. This saves your preference permanently. To re-enable:
  178. ```bash
  179. golf telemetry enable
  180. ```
  181. 2. **During any command**: Add `--no-telemetry` to save your preference:
  182. ```bash
  183. golf init my-project --no-telemetry
  184. ```
  185. Your telemetry preference is stored in `~/.golf/telemetry.json` and persists across all Golf commands.
  186. <div align="center">
  187. Made with ❤️ in Warsaw, Poland and SF
  188. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.