CLI commands and flags

Reference for the mcpgen command line. Version documented: 1.0.0.

This page is generated from cli.BuildSchemaDoc, the exact document the [mcpgen schema/mcpgen/reference/generated/machine-interface/) command emits on stdout, so it cannot drift from the CLI.

Global behavior:

• A leading dash argument (e.g. mcpgen --name weather ...) is shorthand for mcpgen new.
• mcpgen with no arguments on a terminal runs the interactive flow; with no terminal it prints usage and exits 2.
• Every command accepts --json where listed and writes exactly one JSON envelope to stdout; logs go to stderr. Errors are always structured, even without --json.
• Exit codes are stable: 0 ok, 1 failure, 2 usage, 3 exists/not-project, 4 permission, 5 conflict, 6 prerequisite missing. See [machine interface/mcpgen/reference/generated/machine-interface/).

Commands

mcpgen new

Generate a new MCP server project. With no arguments on a TTY, mcpgen new runs interactively. Re-running on an existing mcpgen project requires –force and never overwrites user-modified files.

mcpgen new [dir] [--name] [--module] [--version] [--transport stdio|http] [--port] [--protocol compat|latest-only] [--tool spec.json ...] [--prompt spec.json ...] [--resource spec.json ...] [--features tasks,skills,oauth] [--no-stubs] [--json] [--dry-run] [--force] [--no-check]

Flag	Type	Default	Repeatable	Description
--name	string	example-mcp		Server name
--module	string	derived from name		Go module path
--version	string	0.1.0		Server version (semver)
--transport	string	stdio		stdio|http
--port	int	8080		HTTP port when transport=http
--protocol	string	compat		compat|latest-only (MCP 2026-07-28 only)
--tool	string	—	yes	Tool spec JSON file, optionally name=file.json
--prompt	string	—	yes	Prompt spec JSON file, optionally name=file.json
--resource	string	—	yes	Resource spec JSON file, optionally name=file.json
--features	string	—		Comma-separated opt-in features: tasks,skills,oauth
--no-stubs	bool	—		Do not add the default tool/prompt/resource stubs
--json	bool	—		Emit the JSON envelope on stdout
--dry-run	bool	—		Print the full plan (file tree, create/modify/skip, config summary) as JSON; write nothing
--force	bool	—		Allow generating into an existing directory
--no-check	bool	—		Skip the post-generation validation pipeline

Examples:

mcpgen new ./weather --name weather --module github.com/acme/weather --transport http --json
mcpgen new ./weather --tool tools/forecast.json --json --dry-run

mcpgen add

Add a capability to an existing mcpgen-generated project. Appends to mcpgen.json, creates the user-owned handler file, and inserts registration into the mcpgen marker region (AST-aware). Duplicate IDs exit 5.

mcpgen add tool|prompt|resource <spec.json> [--dir .] [--json] [--dry-run] [--force]

Flag	Type	Default	Repeatable	Description
--dir	string	.		Project root (must contain mcpgen.json)
--json	bool	—		Emit the JSON envelope on stdout
--dry-run	bool	—		Print the plan as JSON; write nothing
--force	bool	—		Overwrite an existing user-owned handler file
--no-check	bool	—		Skip the post-add validation pipeline
--conformance	bool	—		Force the conformance stage of the post-add pipeline on
--no-conformance	bool	—		Disable the conformance stage of the post-add pipeline

Examples:

mcpgen add tool tools/health.json --dir ./weather --json

mcpgen check

Run the verification pipeline: config, tidy, fmt, vet, build, test, conformance (when node/npx present and transport is http), optional inspector smoke. Exit 0 means green; the JSON envelope lists every stage status and a fix hint with file:line of the first failure.

mcpgen check [dir] [--json] [--conformance] [--no-conformance] [--inspector] [--timeout 10m]

Flag	Type	Default	Repeatable	Description
--json	bool	—		Emit the JSON envelope on stdout
--conformance	bool	auto (on when npx present)		Force the conformance stage on
--no-conformance	bool	—		Disable the conformance stage
--inspector	bool	—		Run the Inspector v2 CLI smoke check (debugging aid)
--timeout	duration	10m		Overall pipeline timeout

Examples:

mcpgen check ./weather --json   # loop until exit 0

mcpgen schema

Emit the machine-readable spec of all commands, flags, types, defaults, exit codes, the envelope, and the mcpgen.json JSON Schema. This is the agent self-discovery entry point.

mcpgen schema

mcpgen version

Print the mcpgen version.

mcpgen version [--json]

Flag	Type	Default	Repeatable	Description
--json	bool	—		Emit the JSON envelope on stdout

mcpgen mcp

Run mcpgen itself as an MCP server over stdio, exposing mcpgen_new, mcpgen_add, mcpgen_check, and mcpgen_schema for hosts without shell access.

mcpgen mcp