golf MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

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

라이브 데모

실제 사용 모습

golf.replay ▶ 준비됨

0/0

설치

클라이언트 선택

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

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

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

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

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

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

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

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

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

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

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

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

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

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add golf -- uvx golf

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: golf

Build an internal company MCP with Golf

👤 Platform engineers ⏱ ~60 min advanced

언제 쓸까: You want a single authenticated MCP exposing 20+ internal tools (Jira, Grafana, ticketing) to employees via Claude.

사전 조건

Python 3.11+, uv — astral.sh/uv

흐름

Scaffold

Run uvx golf new acme-mcp and cd in.✓ 복사됨

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

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

→ 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.✓ 복사됨

→ Unauthenticated calls rejected

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

함정

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

언제 쓸까: You already run OTel collectors and want agent tool calls to appear in traces.

흐름

Enable telemetry

In golf.yaml, enable telemetry.otlp with your collector endpoint.✓ 복사됨

→ 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.✓ 복사됨

→ Per-user call graphs

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

함께 쓰기: prometheus

Version prompts alongside code with Golf

👤 Prompt engineers ⏱ ~25 min intermediate

언제 쓸까: Your prompts live in a Notion and drift from what's actually deployed.

흐름

Move prompts into prompts/ dir

Create prompts/triage.py with a prompt template and variables.✓ 복사됨

→ 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✓ 복사됨

→ Regression safety for prompt edits

결과: Prompts ship through the same PR process as code.

조합

다른 MCP와 조합해 10배 효율

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.✓ 복사됨

golf + prometheus

Scrape Golf's metrics endpoint into Prometheus

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

도구

이 MCP가 노출하는 것

도구	입력	언제 호출
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

비용 및 제한

운영 비용

API 쿼터: None — framework runs wherever you host it
호출당 토큰: Depends on tools
금액: Free, open source
팁: Enable telemetry sampling in production (e.g. 10% of tool calls) to control OTel ingest cost

보안

권한, 시크릿, 파급범위

자격 증명 저장: JWT/OAuth secrets via env; Golf never logs them by default

데이터 외부 송신: Wherever your tools call

문제 해결

자주 발생하는 오류와 해결

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

확인: 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

확인: curl -v $OTLP_ENDPOINT/v1/traces

대안

golf 다른 것과 비교

대안	언제 쓰나	단점/장점
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

golf