How-to › Ship an SDK

How to generate an SDK, a CLI, and an MCP Server from one spec#

Generate a Go SDK, a CLI, and an MCP Server from one OpenAPI document, change one operation, and count the edits and commands each route needed.

Audience
API producer
Level
intermediate
Topic
Choose a generator and generate an SDK
Languages
Go and TypeScript
Verified

Read first: Generate your first SDK with sdkgen

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
ogenYou want a typed Go client and accept separate tools for the CLI and the serverGo only, no CLI or MCP output, and an added parameter changed the method’s signatureYou want one tool to own every surface’s names
openapi-mcp-generatorAn MCP Server in TypeScript with one tool per operation, filtered by x-mcpA third set of names, and a build step of its own after every changeAgents need fewer tools than you have operations, and you cannot mark the document
RestishA CLI over any OpenAPI document, with nothing to build or releaseEvery user runs api sync after a change, or keeps the old commandsYou ship one pinned binary per release
sdkgen consumer targetsA Go SDK, CLI, and MCP Server from one model, regenerated in one stepIts opinions on every surface: three CLI words and two read-only tools by defaultYou need every operation on every surface without editing templates
Speakeasy workflow targetsOne vendor, an SDK, a Cobra CLI, and a TypeScript MCP Server from one sourceAn account, and its CLI and MCP targets are graded BetaYou 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.

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

  1. 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 book and bookshelf list-books each 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

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.