Skip to content
mcpgen

FAQ and troubleshooting

Frequently asked questions

Section titled “Frequently asked questions”

Is generation deterministic? Yes. Same mcpgen.json in, same project out. Golden tests in internal/generator/testdata/golden pin the output byte-for-byte.

Can I edit generated files? User-owned files (handlers, prompts, resources, tests): always. mcpgen-owned files: you can, but the next regen skips them with modified since generation (hash mismatch) — your edit wins. Never edit inside // mcpgen:begin/end marker regions; add then exits 5 until you restore them.

How do I remove a tool/prompt/resource? Delete its entry from mcpgen.json, delete its user-owned files first, then mcpgen new <dir> --force --no-check. See add capabilities.

Why is the conformance stage skipped? It runs only when node/npx are present, transport is http, and protocol is compat. stdio has no HTTP endpoint; latest-only rejects the suite’s legacy handshake by design. Force it with --conformance (fails with exit 6 if node/npx are missing).

What does “8/30 checks passed” mean? The suite’s protocol-level scenarios gate; fixture scenarios that need well-known test tools are reported as non-gating. See check and conformance.

Is the HTTP server authenticated? No. It binds to 127.0.0.1 and rejects cross-site Origin headers (403). Enable the oauth feature and wire oauthex.RequireAuth before exposing it on a network. See security model.

Troubleshooting (verified error shapes)

Section titled “Troubleshooting (verified error shapes)”

DIR_EXISTS — exit 3. The target directory exists and is not empty, and you did not pass --force:

{ "ok": false, "error": { "code": "DIR_EXISTS",
  "message": "target directory ./weather exists and is not empty",
  "fix": "pass --force to regenerate an existing mcpgen project ...", "exit_code": 3 } }

Fix: pass --force to regenerate, or choose a new directory.

NOT_MCPGEN_PROJECT — exit 3. mcpgen check ./somewhere where somewhere has no mcpgen.json / .mcpgen/manifest.json. Fix: run from a generated project root, or create one with mcpgen new.

CONFIG_INVALID — exit 2. mcpgen.json failed validation. The message lists every problem, for example an id that violates ^[a-zA-Z0-9_-]+$, a duplicate id, a bad transport, or a port outside 1-65535. Fix: edit mcpgen.json; error.fix points at the file. Recover by fixing the fields, or — if the file is beyond repair — regenerate the project with mcpgen new <dir> --force --no-check after backing up your user-owned files, which regen never touches.

CONFIG_VERSION_UNSUPPORTED — exit 2. Only "version": 1 is supported by mcpgen v1. Fix: set "version": 1 or regenerate.

CONFLICT — exit 5. Duplicate id in mcpgen.json, id already in a marker region, or markers missing/unparseable in a registration file. Fix: choose a different id, or restore the // mcpgen:begin <region> / // mcpgen:end <region> markers (regen with --force recreates the registration files only if they are unmodified — delete a damaged one first and regen recreates it).

PREREQUISITE_MISSING — exit 6. The Go toolchain is not on PATH (every pipeline stops here), or --conformance was forced without node/npx. Fix: install Go 1.26+ or Node.js, or drop the flag.

SPEC_INVALID — exit 2. The spec file passed to add is unreadable or invalid (bad id pattern, bad JSON). Nothing is written. Fix the spec.

A stage failed in check (exit 1). Read error.stage, error.code, and error.fix — fix names the first failure with its file:line, for example first failure: TestGreet (greet_test.go:30); run 'go test -race ./...' in ./weather. Fix, re-run mcpgen check ./weather --json.

Upgrade mcpgen

Section titled “Upgrade mcpgen”
Terminal window
go install github.com/alesr/mcpgen@latest     # or download a release binary
mcpgen version                                  # check what you run

Generated files carry the generator version in their header (// Code generated by mcpgen vX.Y.Z. DO NOT EDIT.) and in .mcpgen/manifest.json. After upgrading, regenerate with mcpgen new <dir> --force --no-check to bring mcpgen-owned files up to date; user-owned files and modified mcpgen-owned files are skipped as always. The tidy stage of check also verifies the generated project still pins go-sdk v1.8.0 — if you hand-downgrade the pin, check fails and tells you to restore it or regen.

Next steps

Section titled “Next steps”