golf MCP — Use Cases, Install & Live Demo

Why use it

Key features

Auto-discovers tools/prompts/resources from directory conventions
Enterprise auth: JWT, OAuth server, API keys, dev tokens
Optional OpenTelemetry — traces tool calls to your existing observability
Minimal boilerplate; focus on the tool logic

Live Demo

What it looks like in practice

golf.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "golf": {
      "command": "uvx",
      "args": [
        "golf"
      ],
      "_inferred": true
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "golf": {
      "command": "uvx",
      "args": [
        "golf"
      ],
      "_inferred": true
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "golf": {
      "command": "uvx",
      "args": [
        "golf"
      ],
      "_inferred": true
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "golf": {
      "command": "uvx",
      "args": [
        "golf"
      ],
      "_inferred": true
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "golf",
      "command": "uvx",
      "args": [
        "golf"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "golf": {
      "command": {
        "path": "uvx",
        "args": [
          "golf"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add golf -- uvx golf

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use golf

Build an internal company MCP with Golf

👤 Platform engineers ⏱ ~60 min advanced

When to use: You want a single authenticated MCP exposing 20+ internal tools (Jira, Grafana, ticketing) to employees via Claude.

Prerequisites

Python 3.11+, uv — astral.sh/uv

Flow

Scaffold

Run uvx golf new acme-mcp and cd in.✓ Copied

→ Project with tools/, prompts/, resources/ dirs
Drop in tool files

Create tools/list_tickets.py exporting an async function. Golf wires the schema automatically.✓ Copied

→ Tool visible at /tools list
Enable JWT auth tied to your IdP

Configure golf.yaml auth: jwt with your IdP's JWKS URL. Require mcp:use scope.✓ Copied

→ Unauthenticated calls rejected

Outcome: A deployable MCP that only authorized employees can call, with traces flowing to your APM.

Pitfalls

Each tool import failure breaks server startup — Golf loads tools eagerly — fix import errors or move heavy deps inside the function

Ship an MCP with OpenTelemetry from day one

👤 SREs, observability engineers ⏱ ~30 min advanced

When to use: You already run OTel collectors and want agent tool calls to appear in traces.

Flow

Enable telemetry

In golf.yaml, enable telemetry.otlp with your collector endpoint.✓ Copied

→ Tool calls appear as spans in your OTel backend
Tag traces with user id from auth

Add a middleware that sets user.id on each span from the JWT sub.✓ Copied

→ Per-user call graphs

Outcome: MCP usage is a first-class citizen in your existing observability.

Combine with: prometheus

Version prompts alongside code with Golf

👤 Prompt engineers ⏱ ~25 min intermediate

When to use: Your prompts live in a Notion and drift from what's actually deployed.

Flow

Move prompts into prompts/ dir

Create prompts/triage.py with a prompt template and variables.✓ Copied

→ Prompt appears in MCP /prompts/list
CI-verify on every commit

Add a test that renders each prompt with sample inputs to catch breaking changes✓ Copied

→ Regression safety for prompt edits

Outcome: Prompts ship through the same PR process as code.

Combinations

Pair with other MCPs for X10 leverage

golf + hyper

Compare a Python-based Golf server against a WASM hyper-mcp plugin model

I have the same tool in Golf and hyper-mcp. Run latency & memory comparison across 100 calls each.✓ Copied

golf + prometheus

Scrape Golf's metrics endpoint into Prometheus

Point my Prometheus at golf's /metrics, then query p99 tool latency with prometheus-mcp.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call
golf new <name>	project_name: str	Start a new server
golf build		Compile tool directories into a server binary/image
golf run	--transport stdio\|http	Local dev or production launch

Cost & Limits

What this costs to run

API quota: None — framework runs wherever you host it
Tokens per call: Depends on tools
Monetary: Free, open source
Tip: Enable telemetry sampling in production (e.g. 10% of tool calls) to control OTel ingest cost

Security

Permissions, secrets, blast radius

Credential storage: JWT/OAuth secrets via env; Golf never logs them by default

Data egress: Wherever your tools call

Troubleshooting

Common errors and fixes

Tool not showing in tools list

Check the file exports the async function with the exact name Golf expects (see framework docs); missing __tool__ metadata is the most common cause

Verify: golf run --debug shows discovery log

JWT validation fails with valid token

JWKS URL unreachable or wrong issuer. Verify with curl; check clock skew on host

Traces not appearing in OTel backend

Golf uses OTLP/HTTP — ensure collector has that receiver enabled, not just gRPC

Verify: curl -v $OTLP_ENDPOINT/v1/traces

Alternatives

golf vs others

Alternative	When to use it instead	Tradeoff
FastMCP	You want something simpler without auth/telemetry features	BYO production concerns
MCP-Nest (NestJS)	Your team is a NestJS shop	TypeScript only
Arcade	Focus on distribution/sharing as much as building	Slightly different target audience

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills