# 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.

Source: https://voxgig.com/howto/sdk-cli-and-mcp-server-from-one-spec

- Audience: api-producer
- Level: intermediate
- Languages: go, typescript
- Verified: 2026-11-22
- Published: 2026-11-21

## 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](/howto/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`](https://ogen.dev/docs/intro/) | 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](https://github.com/harsha-iiiv/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](https://rest.sh/docs/getting-started/connect-to-an-api/) | 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](https://github.com/voxgig/sdkgen) | 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](https://www.speakeasy.com/docs/speakeasy-reference/workflow-file) | 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.

```bash title="generate.sh"
(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.

```bash
node coverage.mjs
```

```text output
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](/howto/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`:

```json title="api.v2.json"
    "/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.

```bash title="regen/sdkgen.sh"
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.

```bash
node change.mjs
```

```text output
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](https://www.speakeasy.com/docs/cli-generation/create-cli). The server comes from
[`speakeasy quickstart --mcp`](https://www.speakeasy.com/docs/standalone-mcp/build-server), and [`x-speakeasy-mcp`](https://www.speakeasy.com/docs/standalone-mcp/customize-tools)
sets `disabled` or `scopes` per operation. Its [maturity
matrix](https://www.speakeasy.com/docs/sdks/languages/maturity) grades the Go SDK GA and both the CLI
and MCP TypeScript targets Beta. Generation needs an account, and [free
accounts](https://www.speakeasy.com/docs/sdks/create-client-sdks) generate one SDK of up to 50
methods. The address of its Gram documentation redirects to its [AI control
plane](https://www.speakeasy.com/docs/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.

```bash title="regen/per-surface.sh"
"$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](https://ogen.dev/docs/config/) 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.

```bash
node --test surfaces.test.mjs
```

```text output
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](/howto/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

- [Generate your first SDK with sdkgen](/howto/first-sdk-with-sdkgen)

- [Generate a Go CLI from a semantic model with sdkgen](/howto/generate-a-go-cli-from-a-semantic-model)

- [Generate an MCP server from an OpenAPI document](/howto/generate-an-mcp-server-from-openapi)

- [Choose Restish, a generated CLI, or a hand-written one](/howto/choose-restish-generated-or-hand-written-cli)

- [Prune a generated MCP server to ten tools an agent can use](/howto/prune-a-generated-mcp-server-to-ten-tools)

## 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](https://www.stainless.com/blog/stainless-is-joining-anthropic/) on May 18, 2026.

[^1]: Held to the rules for MCP tool names, four of the six pass. The [tools
section](https://modelcontextprotocol.io/specification/2026-07-28/server/tools) 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.