I went looking for an MCP server framework that didn't feel like a weekend hack wrapped in buzzwords, and Golf came up a few times in discussions about deploying Model Context Protocol servers beyond toy examples. With 839 stars and a v0.4.0 release targeting the MCP 2026-07-28 spec, it's not vaporware either. So I dug into the repo, the deps, and the actual API surface to figure out whether this is something I'd ship with.
What it actually does
Golf is a Python framework on top of FastMCP that gives you a convention-over-configuration layout for MCP servers. Instead of registering tools, prompts, and resources programmatically, you drop Python files into tools/, prompts/, and resources/ directories, and Golf's build step discovers them, parses the function signatures and Pydantic models, and compiles a runnable MCP server.
The mental model is closer to Flask's old "just put a hello.py in here" feel than to a heavy enterprise framework. A file like tools/payments/charge.py becomes a tool registered as charge_payments. The module docstring is the description, the function signature is the parameter schema, and the return annotation is the output schema. It's pragmatic and it works.
Where Golf separates itself from a thin "scan the filesystem" script is the runtime layer: it bundles JWT auth, an OAuth 2.0 server mode, dev tokens, OpenTelemetry tracing (OTLP HTTP), Prometheus metrics, a PostHog client, and a CLI built on Typer. It's positioning itself as the production-ready answer to the question "I built a FastMCP prototype, now what."
Why this matters right now
The MCP ecosystem is in that awkward phase where everyone agrees the protocol is real and useful, but the tooling story is fragmented. The official mcp Python SDK is solid but low-level. FastMCP made authoring servers pleasant, but it doesn't ship with auth, telemetry, or deployment scaffolding. Most teams I've seen either roll their own wrappers or glue together Starlette middleware, custom token validators, and OTel setup manually.
Golf is trying to occupy that "batteries-included but not bloated" middle ground. The timing makes sense — MCP clients (Claude Desktop, Continue.dev, custom agents) are now stable enough that server authors care about observability and auth rather than just proving the protocol works. The 839 stars and 70 forks suggest there's genuine interest, not just hype traffic.
The Apache-2.0 license is a plus for anyone evaluating it for commercial use. And the fact that it pins fastmcp==4.0.0 and mcp-types>=2.1.1,<3.0.0 shows they're paying attention to the spec evolution, not chasing it.
Key features worth highlighting
1. Convention-based component discovery with sensible naming. Drop a Python file, declare export = your_function, and Golf handles registration. The auto-generated ID scheme (charge_payments from tools/payments/charge.py) is a small but thoughtful touch — it means you can reorganize your project tree without breaking MCP client integrations, as long as you keep paths stable. This is the kind of thing that saves you from writing migration scripts later.
2. Real auth, not just a TODO. auth.py supports JWT (with JWKS, issuer, audience, and scope validation), a full OAuth 2.0 server mode where Golf acts as the authorization server, static tokens for development, and API key extraction. The recent commit fix[auth]: clarify API key extraction semantics shows the auth layer is getting actively refined. For teams that need to put an MCP server in front of real users — not just localhost demos — this saves weeks of work.
3. OpenTelemetry + Prometheus out of the box. The dependency list pulls in opentelemetry-api, opentelemetry-sdk, opentelemetry-instrumentation-asgi, opentelemetry-exporter-otlp-proto-http, and an optional prometheus-client extra. You flip a flag in golf.json and you get distributed tracing. For any team running an MCP server behind a load balancer, this is the difference between "we shipped it" and "we know it's working."
4. Built-in elicitation and sampling utilities. The golf.utilities module exposes elicit, sample, and get_current_context. These wrap the MCP primitives in a way that handles the 2026-07-28 protocol's caller-owned multi-round-trip control flow correctly — you return an InputRequiredResult and the framework re-enters your tool with the answer. This is genuinely tricky to get right, and most blog tutorials gloss over it. Golf's documentation actually shows the correct pattern.
5. A real CLI with init, build dev, and run. golf init your-project-name scaffolds a project. golf build dev validates and compiles. golf run starts the server. It's a small thing, but it means new contributors don't need to read the source to figure out the entry point. Typer + Rich means the CLI output is actually readable.
Who should use this
You should use Golf if:
- You're starting a new MCP project today and prefer file-based organization to programmatic registration. The convention is clean and the boilerplate is genuinely minimal.
- You need JWT or OAuth authentication on day one and don't want to write the middleware yourself. The
auth.pyconfiguration model is straightforward and the recent commits show the auth layer is being hardened. - You want OpenTelemetry tracing without spending a day wiring up the SDK. Flip a config flag and you're exporting spans.
- You're comfortable with a v0.4.0 framework that's labeled "Alpha" on PyPI and are willing to read the docs when something breaks.
You probably should NOT use Golf if:
- You need absolute API stability. This is pre-1.0, the v0.2.0 release was a breaking change for the auth API, and the v0.4.0 release added FastMCP 4 dual-era support. If your team hates upgrading frameworks, wait for 1.0.
- You need a framework that's not dependent on a single maintainer. Looking at the contributor list,
aschleanhas 891 commits out of roughly 898 — this is essentially a solo project with occasional outside help. Bus factor is a real concern for production adoption. - You're building something exotic that doesn't fit the tools/prompts/resources model. Golf's value prop is the convention; if you need to fight the convention, you're better off with raw FastMCP.
- You're locked to Python < 3.10. The
requires-python = ">=3.10"line inpyproject.tomlis non-negotiable.
Concerns and limitations
Let me be specific about what worried me when I read through the repo.
Concentration risk. The top four contributors are aschlean (891), wbbw1 (5), claude (1), and dsonyy (1). That's not a community, that's one very active maintainer plus drive-by PRs. Antoni Gmitruk is listed as the author and appears on most merge commits. If he steps away, the project's trajectory is unclear. For a framework you're going to build a product on, this matters.
The project labels itself Alpha. PyPI classifier says Development Status :: 3 - Alpha. That's honest and matches reality — the API is still moving, breaking changes happened between minor versions, and the 0.x version number is doing real work signaling "don't depend on me yet." If you're building internal tooling, fine. If you're building a product your customers depend on, you need to budget for migration work.
Only 2 open issues. That sounds good until you realize it might mean issues are being closed quickly without resolution, or that the project is so niche that few people hit edge cases. Combined with the contributor concentration, I'd want to see more community engagement — issues, discussions, third-party examples — before calling this mature.
The README truncates mid-sentence. Literally: "## Privacy & Telem" and then it cuts off. The truncated privacy section is something I'd want to read before shipping anything that touches user data, especially since PostHog is in the dependency list. If Golf is phoning home telemetry by default, that's a deployment-time decision I need to make explicitly.
Dependency on FastMCP 4.0.0 with an exact pin. fastmcp==4.0.0 means any FastMCP bug or security issue will block Golf's updates unless the maintainer ships a release quickly. Given the bus factor above, this is a meaningful risk.
The CLI requires golf build dev before golf run. That's an extra step compared to FastMCP's mcp.run() style. Not a deal-breaker, but if you're used to Python's "just run the file" model, it feels like ceremony.
Verdict
Golf is a thoughtful, well-scoped project filling a real gap in the Python MCP tooling landscape. The file-based convention works, the auth layer is more substantial than anything else I've seen in this space, and the OpenTelemetry integration is exactly what production deployments need. The v0.4.0 release targeting the current spec shows the maintainer is tracking the protocol evolution, not lagging behind it.
But it's a v0.4.0 alpha-stage framework maintained primarily by one person. I'd recommend it for:
- Internal tools and prototypes where you can absorb breaking changes.
- Teams that need auth + observability today and don't want to build it themselves.
- Developers willing to read the docs and contribute back when they hit rough edges.
I'd hold off if:
- You're building a customer-facing product with a multi-year horizon.
- Your org has hard requirements around bus factor and corporate backing.
- You need the absolute latest stable API surface — wait for 1.0.
If you're already using FastMCP and finding yourself writing the same auth middleware and OTel setup over and over, Golf will save you real time. Just budget for the upgrade tax and keep an eye on the contributor activity before you commit to it long-term.
Repo: github.com/golf-mcp/golf