Skip to content
mcpgen

Quickstart

There are two ways to use mcpgen, and both run the same code path and the same verification pipeline: let an AI agent drive it (mcpgen is itself an MCP server), or run the commands yourself. Every command below was run against the real CLI; output is trimmed with ....

Path 1: let an AI agent do it

Section titled “Path 1: let an AI agent do it”

Install mcpgen, then add it to your MCP client (Claude Desktop, Cursor, or any MCP host):

Terminal window
go install github.com/alesr/mcpgen@latest
{ "mcpServers": { "mcpgen": { "command": "mcpgen", "args": ["mcp"] } } }

From there, the model does the work. It gets four tools (mcpgen_new, mcpgen_add, mcpgen_check, mcpgen_schema), discovers the contract itself with mcpgen_schema, scaffolds with mcpgen_new, and loops mcpgen_check until the run is green. Tool specs are passed as objects, so the model never writes temporary JSON files.

Tell the agent what you want in plain language, for example: “Create a weather MCP server in Go with a forecast tool, and verify it until the checks pass.”

Two things to know:

  • The host machine needs Go 1.26 or newer. mcpgen_check builds and tests the generated project and fails without it.
  • mcpgen writes only inside generated projects. Implementing the handler stubs needs a filesystem tool or a shell in your client.

The full walkthrough, with the four tools and their inputs, is in drive mcpgen from agents.

Path 2: run it yourself (60 seconds)

Section titled “Path 2: run it yourself (60 seconds)”

1. Install

Section titled “1. Install”
Terminal window
go install github.com/alesr/mcpgen@latest

Requires Go 1.26 or newer. Node.js/npx are optional (conformance suite only).

2. Generate a server

Section titled “2. Generate a server”
Terminal window
mcpgen new ./weather --name weather --module example.com/weather --transport http --json

Real output (trimmed):

{
  "ok": true,
  "result": {
    "dir": "./weather",
    "files_written": [
      ".github/workflows/ci.yml",
      "cmd/weather/main.go",
      "internal/mcpapp/mcpapp.go",
      "internal/mcpapp/tools.go",
      "internal/mcpapp/tools/handlers/greet.go",
      "mcpgen.json",
      "..."
    ],
    "files_skipped": [],
    "check": { "ok": true, "stages": [ { "name": "config", "status": "passed" }, "..." ] }
  },
  "error": null,
  "next_actions": [
    "cd ./weather",
    "mcpgen check ./weather --json",
    "make -C ./weather check"
  ]
}

new runs the full verification pipeline after writing files (unless --no-check). Exit code is 0.

3. Verify

Section titled “3. Verify”
Terminal window
mcpgen check ./weather --json

Human output of the same run looks like this (real output):

[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; ...

Exit 0 means every stage passed. On failure, the JSON envelope carries error.stage, error.code, and error.fix with the file:line of the first failure.

4. Run it

Section titled “4. Run it”
Terminal window
cd weather
go run ./cmd/weather            # listens on 127.0.0.1:8080 by default
curl -s http://127.0.0.1:8080/healthz   # -> ok

5. Extend

Section titled “5. Extend”
Terminal window
mcpgen add tool tools/health.json --dir ./weather --json
mcpgen check ./weather --json

add appends the entry to mcpgen.json, creates the user-owned handler files, and inserts the registration into the marker region of internal/mcpapp/tools.go. Your files are never touched.

Next steps

Section titled “Next steps”