You add an author filter to GET /books. The Go client exposes it as ListBooks(ctx, params),
which breaks every caller. The CLI lacks an --author flag until each user resyncs, and
the MCP Server silently drops the argument an agent sends. Each of the three tools reads the
document at a different moment, so each one falls out of step separately.
What you get
You will end up with a Go SDK, a CLI, and an MCP Server from one OpenAPI document, and a measured count of what one operation change cost on each route. This is for you if you ship all three surfaces and must decide between one generator and one tool per surface.
Short answer
In an sdkgen project with a go target, run npx voxgig-sdkgen target add go-cli and
target add go-mcp, then npm run generate, and the Go SDK, the CLI, and the MCP Server come from
one semantic model. After a spec change, regenerate once and rebuild both binaries. Per-surface
tools such as ogen, Restish, and openapi-mcp-generator each need their own step, and each names
the operation its own way.
You will need
Node 22 or later, Go 1.25 or a Go that can fetch that toolchain, and an OpenAPI 3 document.
Verified 2026-11-22 against
@voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4, ogen v1.24.0,
Restish v2.3.0, and openapi-mcp-generator 5.0.1. The document is the Bookshelf API from
generate your first SDK with sdkgen: five operations, no security
scheme.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
ogen | You want a typed Go client and accept separate tools for the CLI and the server | Go only, no CLI or MCP output, and an added parameter changed the method’s signature | You want one tool to own every surface’s names |
| openapi-mcp-generator | An MCP Server in TypeScript with one tool per operation, filtered by x-mcp | A third set of names, and a build step of its own after every change | Agents need fewer tools than you have operations, and you cannot mark the document |
| Restish | A CLI over any OpenAPI document, with nothing to build or release | Every user runs api sync after a change, or keeps the old commands | You ship one pinned binary per release |
| sdkgen consumer targets | A Go SDK, CLI, and MCP Server from one model, regenerated in one step | Its opinions on every surface: three CLI words and two read-only tools by default | You need every operation on every surface without editing templates |
| Speakeasy workflow targets | One vendor, an SDK, a Cobra CLI, and a TypeScript MCP Server from one source | An account, and its CLI and MCP targets are graded Beta | You cannot send the document to a hosted service |
Voxgig maintains sdkgen, the subject of this page. Read its row’s last cell before the rest.
The per-surface route lets each tool do its own job well: ogen writes a typed client, Restish
needs no release at all, and openapi-mcp-generator names every operation’s arguments. The cost is
three sets of names and three steps that can fall out of step. sdkgen and Speakeasy each give you
one place to regenerate, and in exchange every surface inherits one generator’s choices.
Add the CLI and MCP Server to a Go project
Scaffold a project with a go target, generate it, then add the two consumer targets. Each wraps
the Go SDK beside it.
(cd "$WORK" && npx --yes @voxgig/create-sdkgen@0.31.9 bookshelf --def api.json --target go)
(cd "$WORK/bookshelf-sdk/.sdk" && npm run generate)
echo "generate: 15% add the two consumer targets and generate again"
(cd "$WORK/bookshelf-sdk/.sdk" && npx voxgig-sdkgen target add go-cli && npx voxgig-sdkgen target add go-mcp && npm run generate)
generate.sh then builds go-cli/ and go-mcp/ with go build, runs the per-surface tools on
the same document, and calls record.mjs, which drives every surface against a stand-in API.
Nothing on this page regenerates when you rerun a command below: each reads the committed output.
Read what each surface covers
One model does not mean one coverage. coverage.mjs reads the generated CLI words, the MCP tools,
the client methods, and Restish’s command list.
node coverage.mjs
api.v2.json: 5 operations
sdkgen Go SDK (go) 5 of 5 Book.List, Book.Create, Book.Load, Book.Update, Book.Remove
sdkgen CLI (go-cli) 3 of 5 list book, load book, update book
missing: POST /books, DELETE /books/{bookId}
sdkgen MCP Server (go-mcp) 2 of 5 bookshelf_list, bookshelf_load
missing: POST /books, PATCH /books/{bookId}, DELETE /books/{bookId}
per-surface Go SDK (ogen) 5 of 5 ListBooks, CreateBook, GetBook, UpdateBook, DeleteBook
per-surface CLI (restish) 5 of 5 bookshelf list-books, bookshelf create-book, bookshelf get-book, bookshelf update-book, bookshelf delete-book
per-surface MCP Server (openapi-mcp-generator) 5 of 5 listBooks, createBook, getBook, updateBook, deleteBook
with main: kit: target: 'go-mcp': tool: write: true in .sdk/model/project.aontu:
sdkgen MCP Server (go-mcp) 5 of 5 bookshelf_create, bookshelf_list, bookshelf_load, bookshelf_remove, bookshelf_update
the six names for GET /books:
Go SDK (go) Book.List
CLI (go-cli) list book
MCP Server (go-mcp) bookshelf_list
Go SDK (ogen) ListBooks
CLI (restish) bookshelf list-books
MCP Server (openapi-mcp-generator) listBooks
The stock sdkgen CLI stops at three words, and the stock MCP Server at two read-only tools, with
the entity as an argument rather than one tool per operation. The write switch is off by default.
Turned on in .sdk/model/project.aontu, it adds bookshelf_create, bookshelf_update and
bookshelf_remove, as the second block shows and generate an MCP server from a semantic
model explains. The CLI’s create and remove
words need fragment edits. The per-surface tools cover all five operations, under three naming
schemes.1
Change one operation and count the touches
The change adds one optional query parameter to GET /books:
"/books": {
"get": {
"operationId": "listBooks",
"parameters": [{ "name": "author", "in": "query", "required": false,
"schema": { "type": "string" } }],
After the edit, sdkgen needs four commands. The scaffold keeps its own copy of the document in
.sdk/def/, so the first one copies the edit in.
cp "$SPEC" "$WORK/bookshelf-sdk/.sdk/def/api.json"
npm --prefix "$WORK/bookshelf-sdk/.sdk" run generate
go build -C "$WORK/bookshelf-sdk/go-cli" -o "$BIN/bookshelf-cli" .
go build -C "$WORK/bookshelf-sdk/go-mcp" -o "$BIN/bookshelf-mcp" .
record.mjs ran each route’s regeneration script line by line, compiled one caller of each Go
SDK before and after, and asked every surface for one author’s books. change.mjs reads the
records and the two committed diffs.
node change.mjs
the change: api.json -> api.v2.json, GET /books gains an optional author query parameter
sdkgen: 6 places touched: the spec edit, 4 commands (regen/sdkgen.sh) and one caller
files the generators changed: Go SDK 2, CLI 0, MCP Server 0, model 1
callers/sdkgen/main.go: compiled before, fails after: main.go:20:48: unknown field Title in struct literal of type entity.BookListMatch
per-surface: 6 places touched: the spec edit, 4 commands (regen/per-surface.sh) and one caller
files the generators changed: Go SDK 2, CLI 0, MCP Server 1
callers/ogen/main.go: compiled before, fails after: main.go:15:28: not enough arguments in call to client.ListBooks
asked for the books by one author, each surface sent:
before the change
sdkgen go-cli, list book free-form match map GET /v1/books?author=Octavia E. Butler
sdkgen go-mcp, bookshelf_list arguments: entity, query GET /v1/books?author=Octavia E. Butler
openapi-mcp-generator, listBooks arguments: none GET /v1/books
restish, bookshelf list-books no --author flag exit 2, unknown flag: --author; did you mean --rsh-auth?
after the change
sdkgen go-cli, list book free-form match map GET /v1/books?author=Octavia E. Butler
sdkgen go-mcp, bookshelf_list arguments: entity, query GET /v1/books?author=Octavia E. Butler
openapi-mcp-generator, listBooks arguments: author GET /v1/books?author=Octavia E. Butler
restish, bookshelf list-books help lists --author GET /v1/books?author=Octavia E. Butler
On this change the two routes tie on the count, six each, so the count alone does not decide. What differs is where the touches land and what each surface tells its user.
sdkgen’s CLI and MCP Server did not change at all, because both pass a match map through as query
parameters. They sent author before the document declared it. The tool’s schema still names only
entity and query, so an agent learns of the filter from somewhere else. The typed Go match narrowed
to Author, the one declared parameter, and lost Id, Published and Title. Only the typed
call broke, and it was asking for a filter the server refuses; the untyped call still compiled.
On the per-surface route the openapi-mcp-generator server named author once rebuilt, and before
that it dropped the argument and listed every book. ogen moved ListBooks to a parameters
struct, so every caller broke, including callers that never filter. Its fourth command, the
Restish sync, runs on each user’s machine, where all four of sdkgen’s run in your build.
Get the three surfaces from Speakeasy or per-surface tools
Speakeasy puts all three surfaces in one workflow.yaml: one source, then targets of type go,
cli, and mcp-typescript, regenerated together by speakeasy run. Its CLI is written in Go on
Cobra and wraps a generated Go SDK, per its CLI
guide. The server comes from
speakeasy quickstart --mcp, and x-speakeasy-mcp
sets disabled or scopes per operation. Its maturity
matrix grades the Go SDK GA and both the CLI
and MCP TypeScript targets Beta. Generation needs an account, and free
accounts generate one SDK of up to 50
methods. The address of its Gram documentation redirects to its AI control
plane page.
ogen generates a Go client and server and nothing else, so its route is the per-surface one:
Restish for the CLI and openapi-mcp-generator for the server. These four lines are its share of the
count.
"$WORK/bin/ogen" --config ogen.yml --target "$WORK/ogen/bookshelf" --package bookshelf --clean "$SPEC"
npx --yes openapi-mcp-generator@5.0.1 -i "$SPEC" -o "$WORK/omg" --force
npm --prefix "$WORK/omg" run build
"$WORK/bin/restish" api sync bookshelf
ogen.yml disables the paths/server and ogen/otel features, as its configuration
page documents. The last line is not yours to run: every user with
the API configured runs it, or keeps the old commands.
Check it worked
The test reads the committed records and generated files, and fails if either route’s count, a surface’s coverage, or what reached the stand-in differs from the earlier output.
node --test surfaces.test.mjs
1..14
# tests 14
# suites 0
# pass 14
# fail 0
# cancelled 0
# skipped 0
# todo 0
One test asserts that recorded/sdkgen.diff touches no file under go-cli/ or go-mcp/.
Another checks that each regeneration record matches its committed script line for line, and a
third that the stock server in the coverage table is the one with the write switch off.
When it goes wrong
An agent sees hundreds of tools and picks the wrong one. openapi-mcp-generator makes one tool per
operation, so a document with 300 operations gives 300 tools. Mark operations with x-mcp and pass
--default-include false, as prune a generated MCP server to ten
tools does. sdkgen registers one tool per verb
and takes the entity as an enum argument in tools.go, so its count follows the verbs. Speakeasy’s
lever is x-speakeasy-mcp.
A user reports that --author is an unknown flag after your release. Restish serves its cached
copy of the document until restish api sync bookshelf runs. Put the sync in your release notes,
or ship a pinned CLI instead.
An agent never filters by author on the sdkgen server. The query argument is a free-form map, so
the schema carries no parameter names. Name them in the tool description, whose text is in
.sdk/src/cmp/go-mcp/Main_go-mcp.ts.
When not to do this
Do not adopt sdkgen to get three surfaces if your users need every operation on the CLI. Its stock CLI gives three words, and the other two mean fragment edits you then carry through each regeneration. The MCP Server’s writes come back with one boolean, which turns on create, update, and remove together. The newest sdkgen and apidef releases generated the same words and tools in a second scaffold.
Do not count commands and stop there. Both routes cost six touches here, and the difference is which names agree and which surface tells its user about a change.
Pick Speakeasy when a vendor should own the three surfaces and you can send it the document. Pick the per-surface route when the best tool per surface matters more than one set of names. Restish also beats any generated CLI for an internal API whose users can run a sync.
Related how-tos
Last verified
Verified 2026-11-22 against Node 22.23.5, Go 1.25.0, @voxgig/create-sdkgen 0.31.9,
@voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4, ogen v1.24.0, Restish v2.3.0, and
openapi-mcp-generator 5.0.1, with the second scaffold on @voxgig/sdkgen 4.45.0 and
@voxgig/apidef 8.33.1. generate.sh and record.mjs ran each tool and committed what they saw, and a second
run reproduced every file; the commands on this page reread it. Speakeasy was not run, because it needs an account: its
targets, extension, and grades come from its documentation as fetched that day. Stainless, whose
SDK generator the leaf also named, announced it was winding down its hosted
products on May 18, 2026.
Footnotes
-
Held to the rules for MCP tool names, four of the six pass. The tools section of the specification lists letters, digits, the underscore, the hyphen, and the dot as the only characters a name should use, and says a name should not contain spaces.
list bookandbookshelf list-bookseach contain one, because both are CLI commands that a shell reads as two arguments, so the MCP rule never applies to them. ↩︎ Back to text