mcpgen

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.

Why mcpgen

1. Safe regeneration. Every generated file is mcpgen-owned or user-owned, tracked with a sha256 in .mcpgen/manifest.json. Regeneration never overwrites your code.

2. Built-in verification. mcpgen check runs config validation, tidy, fmt, vet, build, go test -race, and the official MCP conformance suite. Exit 0 means green.

3. Agent-friendly. Every command emits one JSON envelope (--json) with stable exit codes and fix hints, so agents loop new → check → fix until exit 0. mcpgen can also run as an MCP server, so an AI client can drive it without shell access.

Related MCP server: MCP Tool Factory

Install

Requires Go 1.27+. Node.js/npx are optional (conformance suite only).

go install github.com/alesr/mcpgen@latest

Release binaries for Linux, macOS, and Windows are on the Releases page (tags vX.Y.Z, built by goreleaser).

Quickstart (60 seconds)

# 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 --json

Real 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.

Use it from an AI agent

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.

What you get

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.

Features

• 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 streamable http on /mcp with /healthz. Loopback bind 127.0.0.1:<port> by default; cross-site Origin rejected (403).

• Protocol modes: compat (default, negotiates down to legacy versions) or latest-only (2026-07-28 only).

• Opt-in features (--features tasks,skills,oauth): tasks stub, skills served from skills/, commented OAuth wiring for 2026-07-28 authorization.

• Machine interface: --json envelope (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.

Status and limitations

• 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 passed with 22 non-gating fixture failures; that is expected, not a bug.

• The generated HTTP server has no authentication unless you enable and wire the oauth feature. It binds to loopback and rejects cross-site Origins, which is the default protection.

• mcpgen.json supports config version 1 only.

• mcpgen v0.3.2; generated servers pin go-sdk v1.8.0 (the tidy check stage enforces the pin).

Documentation

• 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-build for the docs site.

License

MIT. See LICENSE.