mcpgen is a CLI that generates, extends, and verifies MCP (Model Context Protocol) servers in Go. Generated projects build on the official go-sdk v1.8.0 and target MCP spec 2026-07-28.
Full documentation: stdout.alesr.me/mcpgen.
- Safe regeneration. Every generated file is
mcpgen-owned oruser-owned, tracked with a sha256 in.mcpgen/manifest.json. Regeneration never overwrites your code. - Built-in verification.
mcpgen checkruns config validation, tidy, fmt, vet, build,go test -race, and the official MCP conformance suite. Exit 0 means green. - Agent-friendly. Every command emits one JSON envelope (
--json) with stable exit codes andfixhints, so agents loopnew → check → fixuntil exit 0. mcpgen can also run as an MCP server, so an AI client can drive it without shell access.
Requires Go 1.27+. Node.js/npx are optional (conformance suite only).
go install github.com/alesr/mcpgen@latestRelease binaries for Linux, macOS, and Windows are on the Releases page (tags vX.Y.Z, built by goreleaser).
# 1. Generate an HTTP MCP server (runs the check pipeline after writing)
mcpgen new ./weather --name weather --module example.com/weather --transport http --json
# 2. Verify until green (exit 0 = every stage passed)
mcpgen check ./weather --json
# 3. Run it (loopback by default) and probe it
cd weather && go run ./cmd/weather &
curl -s http://127.0.0.1:8080/healthz # -> ok
# 4. Extend at any time; your files are never touched
mcpgen add tool tools/health.json --dir ./weather --json
mcpgen check ./weather --jsonReal check output (trimmed):
[passed] config — mcpgen.json valid (version 1, 1 tools, 1 prompts, 1 resources)
[passed] serverjson — server.json valid (MCP Registry descriptor)
[passed] tidy — go mod tidy
[passed] fmt — gofmt clean
[passed] vet — go vet clean
[passed] build — go build ok
[passed] test — go test -race ok
[passed] conformance — conformance passed against http://127.0.0.1:61255/mcp: 8/30 checks passed; ...
mcpgen with no arguments runs an interactive flow. mcpgen schema prints the full machine-readable contract (commands, flags, exit codes, envelope, mcpgen.json JSON Schema), the self-discovery entry point for agents. The same walkthrough, step by step: Quickstart.
mcpgen mcp runs mcpgen itself as a stdio MCP server. An MCP client (Claude Desktop, Cursor, or any MCP host) can then generate, extend, and verify MCP servers for you. Add it to your client:
{ "mcpServers": { "mcpgen": { "command": "mcpgen", "args": ["mcp"] } } }The client gets four tools: mcpgen_new, mcpgen_add, mcpgen_check, mcpgen_schema. They use the same code path as the CLI. The model discovers the contract itself, calls mcpgen_new, implements the stubs, and loops mcpgen_check until green. Tool specs are passed as objects, not files. Writing the handler files needs a filesystem tool or shell on the host. See drive mcpgen from agents.
A fresh mcpgen new ./weather --name weather --module example.com/weather produces (verified against a real generation):
weather/
├── cmd/weather/main.go entrypoint (stdio, or HTTP server with -addr)
├── internal/mcpapp/
│ ├── mcpapp.go server wiring (stateless HTTP, protocol versions)
│ ├── tools.go / prompts.go / resources.go registration + // mcpgen:begin/end markers
│ ├── tools/handlers/greet.go (+_test.go) user-owned: your implementation
│ ├── prompts/welcome.go (+_test.go) user-owned
│ └── resources/readme.go (+_test.go) user-owned
├── mcpgen.json single source of truth (version 1)
├── .mcpgen/manifest.json owner + sha256 per file
├── server.json, Dockerfile, Makefile, .github/workflows/ci.yml, go.mod (pins go-sdk v1.8.0)
Tool handlers are typed (mcp.AddTool[In, Out]): <Tool>Input/<Tool>Output structs are derived from the tool's JSON Schema, and the SDK validates arguments before your handler runs.
- Commands:
new,add tool|prompt|resource,check,schema,version,mcp(mcpgen itself as a stdio MCP server), plus an interactive TUI. - Transports:
stdio(default) and stateless streamablehttpon/mcpwith/healthz. Loopback bind127.0.0.1:<port>by default; cross-siteOriginrejected (403). - Protocol modes:
compat(default, negotiates down to legacy versions) orlatest-only(2026-07-28 only). - Opt-in features (
--features tasks,skills,oauth): tasks stub, skills served fromskills/, commented OAuth wiring for 2026-07-28 authorization. - Machine interface:
--jsonenvelope (ok,result,error{stage,code,message,fix,command,exit_code},next_actions). Exit codes: 0 ok, 1 failure, 2 usage, 3 exists/not-project, 4 permission, 5 conflict, 6 prerequisite missing.
- The conformance gate runs only the scenarios the official suite can run against a generated server: protocol-level scenarios gate; capability-fixture scenarios (which need well-known test tools) are reported as non-gating. A default server shows
8/30 checks passedwith 22 non-gating fixture failures; that is expected, not a bug. - The generated HTTP server has no authentication unless you enable and wire the
oauthfeature. It binds to loopback and rejects cross-site Origins, which is the default protection. mcpgen.jsonsupports config version 1 only.mcpgenv0.3.2; generated servers pingo-sdk v1.8.0(thetidycheck stage enforces the pin).
- Docs site: quickstart, end-to-end tutorial, concepts (ownership model, marker regions, security), how-to guides, and a generated reference (CLI,
mcpgen.json, exit codes, file tree). AGENTS.md: repo guidance for coding agents.SKILL.md: the agent loop as a skill.- Contributing: architecture, local checks (
make check), releases. - Development:
make check(tidy, fmt, vet, race tests),make golden,make docs-gen/make docs-buildfor the docs site.
MIT. See LICENSE.