Machine interface (JSON envelope, exit codes, error codes)

Agents should drive mcpgen through --json and branch on exit codes. This page is generated from internal/cli (exit and error code constants parsed from exit.go with go/parser) and from cli.BuildSchemaDoc — the document mcpgen schema emits.

JSON envelope

Every command emits one JSON envelope on stdout when –json is set. Errors are always structured, even without –json. next_actions is always present on success and recoverable failure; fix carries the single most actionable next step (with file:line when known).

stdout: JSON envelope (–json) or clean human output; never mixed with logs
stderr: progress and log lines

Field	Meaning
`error`	null, or {stage, code, message, fix, command, exit_code}
`next_actions`	array of strings, always present on success and recoverable failure
`ok`	bool - true on success
`result`	command-specific payload, null on error

Success example:

{
  "ok": true,
  "result": { "dir": "./weather", "files_written": ["cmd/weather/main.go"], "files_skipped": [] },
  "error": null,
  "next_actions": ["cd ./weather", "mcpgen check ./weather --json"]
}

Failure example (always structured, even without --json):

{
  "ok": false,
  "result": null,
  "error": {
    "stage": "test",
    "code": "TESTS_FAILED",
    "message": "1 of 3 tests failed",
    "fix": "first failure: TestGreet (greet_test.go:30); run 'go test -race ./...' in ./weather",
    "command": "go test -race ./...",
    "exit_code": 1
  },
  "next_actions": ["fix the failing test, then re-run mcpgen check ./weather --json"]
}

Exit codes

Stable and safe to branch on. The constants below are parsed from internal/cli/exit.go.

Code	Constant	Meaning
0	`ExitOK`	Success
1	`ExitFailure`	General failure (build/test/conformance failed)
2	`ExitUsage`	Usage error (bad flags/args, unknown config version)
3	`ExitExists`	Target directory exists and not –force / project not mcpgen-generated
4	`ExitPermission`	Permission denied (filesystem, port)
5	`ExitConflict`	Conflict (name already registered in project, markers missing)
6	`ExitPrerequisite`	Prerequisite missing (go toolchain, node/npx for conformance)

Error codes

Attached to error.code in the envelope. Constants parsed from internal/cli/exit.go.

Code	Constant	Meaning	Typical exit code
`BUILD_FAILED`	`CodeBuildFailed`	`go build` failed	1
`CONFIG_INVALID`	`CodeConfigInvalid`	mcpgen.json failed validation	2
`CONFIG_VERSION_UNSUPPORTED`	`CodeConfigVersion`	mcpgen.json version is not supported (v1 supports only version 1)	2
`CONFLICT`	`CodeConflict`	duplicate id, or mcpgen markers missing/edited in a registration file	5
`CONFORMANCE_FAILED`	`CodeConformanceFailed`	the MCP conformance suite reported gating failures	1
`DIR_EXISTS`	`CodeDirExists`	target directory exists and is not empty without `--force`	3
`FMT_FAILED`	`CodeFmtFailed`	`gofmt -l` reported files	1
`GENERATE_FAILED`	`CodeGenerateFailed`	template rendering or file generation failed	1
`IO_ERROR`	`CodeIO`	a file could not be read or written	1 or 4
`INSPECTOR_FAILED`	`CodeInspectorFailed`	the Inspector smoke check failed	1
`INTERNAL`	`CodeInternal`	unexpected internal error	1
`NOT_MCPGEN_PROJECT`	`CodeNotMCPGenProject`	the directory is not an mcpgen-generated project	3
`PERMISSION_DENIED`	`CodePermission`	permission denied (filesystem or port)	4
`PREREQUISITE_MISSING`	`CodePrerequisite`	a prerequisite is missing (Go toolchain, or node/npx for a forced conformance run)	6
`SPEC_INVALID`	`CodeSpecInvalid`	a tool/prompt/resource spec file is invalid	2
`STAGE_FAILED`	`CodeStageFailed`	a check stage failed without a more specific code	1
`TESTS_FAILED`	`CodeTestsFailed`	`go test -race` failed	1
`TIDY_FAILED`	`CodeTidyFailed`	`go mod tidy` failed or the go-sdk pin is missing	1
`USAGE`	`CodeUsage`	bad flags or arguments	2
`VET_FAILED`	`CodeVetFailed`	`go vet` failed	1

Self-discovery

mcpgen schema prints the full machine-readable contract (this envelope, all commands and flags, exit codes, and the mcpgen.json JSON Schema) as one JSON document on stdout. mcpgen mcp exposes the same operations as MCP tools (mcpgen_new, mcpgen_add, mcpgen_check, mcpgen_schema) over stdio for hosts without shell access.