Skip to content
mcpgen

Drive mcpgen from an AI agent

mcpgen is built AI-first. One code path (internal/ops) serves two surfaces, so they cannot diverge:

  1. Shell agents (Claude Code, Cursor CLI, terminals, scripts) run the CLI with --json and branch on exit codes.
  2. MCP hosts without shell access (Claude Desktop, web clients, any MCP client) install mcpgen itself as an MCP server — mcpgen mcp. The model then drives mcpgen with tools.

Both paths follow the same loop:

discover (mcpgen schema)
  → mcpgen new            # bootstrap (dry-run first to preview)
  → implement the stubs    # user-owned files
  → mcpgen check          # loop until green
  → mcpgen add            # extend, then check again

Path 1: shell agents

Section titled “Path 1: shell agents”

Read the envelope: ok, result, error (stage, code, message, fix, command, exit_code), and next_actions (always present on success and recoverable failure). Progress and logs go to stderr; stdout carries only the envelope or clean human text. Errors are always structured, even without --json.

Terminal window
mcpgen new ./weather --name weather --module example.com/weather --transport http --json
mcpgen check ./weather --json     # loop until exit 0

Exit codes are stable — branch on them:

Code Meaning
0 success
1 general failure (build/test/conformance failed)
2 usage error (bad flags/args, unknown config version, invalid spec)
3 target dir exists without --force, or not an mcpgen project
4 permission denied
5 conflict (duplicate id, markers missing/edited)
6 prerequisite missing (Go toolchain, node/npx for forced conformance)

The exit-code, error-code, and envelope tables are generated from source. See the machine interface page.

Self-discovery: mcpgen schema prints one JSON document with every command, flag, type, default, and example, the exit-code table, the envelope description, and the full mcpgen.json JSON Schema (config_json_schema). It is the same document that generates the CLI reference page, so it never drifts from the docs.

Path 2: mcpgen as an MCP server

Section titled “Path 2: mcpgen as an MCP server”

mcpgen mcp runs mcpgen itself as a stdio MCP server. Add it to any MCP client:

{ "mcpServers": { "mcpgen": { "command": "mcpgen", "args": ["mcp"] } } }

The server exposes four tools (captured from a real tools/list):

Tool What it does Key inputs
mcpgen_new Generate a new project (mcpgen new) dir, name, module, version, transport, port, protocol, tools/prompts/resources (spec objects), features, dryRun, force, noCheck
mcpgen_add Add a tool, prompt, or resource (mcpgen add) kind (tool/prompt/resource), spec (the spec object — no file needed), dir, force, dryRun
mcpgen_check Run the verification pipeline (mcpgen check) dir, conformance, inspector, timeoutSec (default 600)
mcpgen_schema Emit the full contract (mcpgen schema) none

Two properties matter for model-driven use:

  • Specs are objects, not files. mcpgen_add takes the spec inline (spec: {id, title, inputSchema, ...}). The model never writes temporary JSON files.
  • Results are structured. Each of mcpgen_new, mcpgen_add, and mcpgen_check returns ok, the result payload, and on failure error with code, exit_code, and fix — the same fields the CLI envelope carries (without stage and command). mcpgen_new also returns next_actions. mcpgen_schema returns the bare schema document.

Real call, captured over stdio (tools/call mcpgen_new with dryRun: true; output trimmed):

{
  "ok": true,
  "dir": "./weather",
  "plan": { "...": "the full dry-run file plan" },
  "next_actions": [
    "implement handler stubs",
    "mcpgen_check until ok=true"
  ]
}

The model loop inside the client is then:

  1. Call mcpgen_schema to learn the contract.
  2. Call mcpgen_new (optionally dryRun first) to scaffold.
  3. Write the handler logic in the user-owned files.
  4. Call mcpgen_check; read fix on failure; repeat until ok: true.
  5. Call mcpgen_add to extend, then mcpgen_check again.

Step 3 needs a filesystem tool or a shell in the client. The mcpgen tools write only inside generated projects; they do not replace a filesystem server.

Note: the host machine needs the Go toolchain. mcpgen_check fails without it (exit code 6, PREREQUISITE_MISSING). mcpgen_new fails too, unless dryRun or noCheck is set. Node.js/npx are optional, for the conformance stage.

SKILL.md

Section titled “SKILL.md”

The repository ships a SKILL.md that encodes this loop for agent runtimes that support skills. It states the same contract: schema first, structured results always, loop check until green, never edit marker regions.

Next steps

Section titled “Next steps”