Your Go SDK calls the vessel registry by entity, Vessel().Load, while the MCP server beside it
was generated by another tool from the same document and calls it getVessel. A field renamed in
the spec reaches one of them after a regeneration and the other after somebody notices. Agents
and SDK users then describe the same API in two vocabularies.
What you get
You will end up with a Go MCP server generated from the model that writes your Go SDK. An Inspector run lists its tools, calls one, and diffs the list after a spec change. This is for you if you already generate an SDK with sdkgen.
Short answer
Scaffold an sdkgen project with --target go --target go-mcp, set
main: kit: target: 'go-mcp': tool: write: true in .sdk/model/project.aontu if agents may
write, and run npm run generate. The Go MCP server registers one tool per operation, such as
harbor_load, with the entity as an argument. Read .sdk/model/entity first, because a POST
action endpoint can land inside create.
You will need
An OpenAPI 3 document, Node 22.23.4 or later, and Go 1.25 or a Go that can fetch that toolchain.
Verified 2026-11-20 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, and @modelcontextprotocol/inspector 2.16.0.
The document here, api.v1.json, is a Harbor API with six operations on vessels, a tide gauge,
and one action, POST /vessels/{vesselId}/depart. api.v2.json adds a DELETE. The generated
server is built on the official Go MCP SDK.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Fern MCP generator | You want a hosted server at a stable URL, with tool names set per operation | A Fern account to deploy, and a hosted service between the agent and your API | You must run the server yourself, offline, or without a vendor account |
| openapi-mcp-generator | One TypeScript server, one tool per operation, filtered by tag or operationId | A second generator beside your SDK’s, so the two vocabularies drift apart | Your SDK and server should share one set of names |
| sdkgen go-mcp target | You generate the SDK with sdkgen and want the server from the same model | Tools per operation with an entity argument, and a classification you must read before you trust it | The API is a set of actions, which the entity model folds away |
| Swagger Codegen with a hand-written server | A generated Go client exists and you want each tool written by hand | No MCP target, so every tool, schema, and description is yours to write and keep | More than a handful of tools, or a spec that changes weekly |
Voxgig maintains sdkgen, which this page is about. The sdkgen row names the case where it is the wrong choice.
Fern and openapi-mcp-generator map operations to tools, which keeps every endpoint and costs a second vocabulary beside your SDK. sdkgen keeps one vocabulary because the SDK and the server come from one model, and the cost is a model whose guesses you have to read. Swagger Codegen costs the most labor and gives the most control.
Generate the SDK and the server from one model
Scaffold with both Go targets, switch on the write tools, and generate. generate.sh in the
sample holds the full sequence, version-pinned.
cp api.v1.json api.json
npx --yes @voxgig/create-sdkgen@0.31.9 harbor --def api.json --target go --target go-mcp
cd harbor-sdk/.sdk
npm run generate # v1-read-only: the write switch at its default
cp ../go-mcp/tools.go ../../tools.v1-read-only.go
printf "\nmain: kit: target: 'go-mcp': tool: write: true\n" >> model/project.aontu
npm run generate # v1: model/entity, ../go, ../go-mcp
The write switch is off by default, and the
model reference gives the
reason: an agent calling one changes the API’s data. The first generate, before the switch, wrote
a server with only harbor_list and harbor_load. go-mcp/ holds main.go and tools.go, and
its go.mod points at the sibling go/ SDK with a relative replace. The sample commits the
output of four runs, and build.sh builds a server from each.
bash build.sh
harbor-mcp-v1
harbor-mcp-v1-read-only
harbor-mcp-v2
harbor-mcp-v2-guide
Read the model before you trust the tools
Every tool comes from the classification in .sdk/model/entity. model.mjs prints the v2 run’s
copy of it.
node model.mjs v2
tide
load GET /tide
vessel
create POST /vessels/{vesselId}/depart $action: depart
create POST /vessels
list GET /vessels
load GET /vessels/{vesselId}
remove DELETE /vessels/{vesselId}
update PATCH /vessels/{vesselId}
Seven operations reached the model, and one of them is in disguise. The tide gauge became a
tide entity with load. The depart action became a second point of vessel.create, selected by
a $action key.
List and call the tools with MCP Inspector
MCP Inspector has a command line mode, and
inspect.mjs runs it against each binary with a stand-in API on 127.0.0.1 behind it.
node inspect.mjs list v2
5 tools from bin/harbor-mcp-v2
harbor_create destructiveHint=false entity: vessel
harbor_list readOnlyHint=true entity: vessel
harbor_load readOnlyHint=true entity: tide | vessel
harbor_remove destructiveHint=true entity: vessel
harbor_update destructiveHint=true entity: vessel
The server registers one tool per operation and names the entity in an enum. So harbor_load
serves both entities, and the agent picks the entity as an argument. The read-only pair carries
readOnlyHint, and the three writes carry destructiveHint.
node inspect.mjs call v2 harbor_load entity=vessel 'query={"id":"v1"}'
call harbor_load entity=vessel query={"id":"v1"}
the API received GET /v1/vessels/v1
isError: false
text: { "berth": "B4", "id": "v1", "name": "Maria Theresa", "status": "moored" }
One read-only call reached the API and returned the stand-in’s record. The server reads the base
URL from HARBOR_BASE, and inspect.mjs passes the stand-in’s address with the Inspector’s -e
flag.1
Regenerate after the spec change
Copy api.v2.json into .sdk/def/api.json and run npm run generate again. Then compare the two
servers’ tool lists.
node inspect.mjs diff v1 v2
v1: 4 tools, v2: 5 tools
harbor_create unchanged, byte for byte
harbor_list unchanged, byte for byte
harbor_load unchanged, byte for byte
harbor_remove added
harbor_update unchanged, byte for byte
The DELETE became harbor_remove, and the four existing tools came back identical in name,
description, schema, and annotations. In the same run the Go SDK’s Vessel().Remove, a stub that
returned UnsupportedOp in v1, became a real call, so the two surfaces moved together.
Do the same with Fern and Swagger Codegen
Fern generates an MCP server as a target of its own. In the current sdk-config.yml format, a
target with language: mcp and delivery: hosted deploys one tool per supported operation to
https://<your-org>.fernmcp.dev/<slug>, and x-fern-mcp-name on an operation names its tool. Its
quickstart, badged Beta,
requires a Fern account and fern login to deploy. delivery: zip writes a Node server to run yourself instead. Regenerating with
the same slug updates the server in place, which is the property this page tests for sdkgen.
Swagger Codegen has no MCP target. Its live client list names nineteen client generators and no MCP server.2 What it gives you is a client with one method per operation, which you wrap in tools by hand.
grep -o '^func (a \*DefaultApiService) [A-Za-z]*' swagger-codegen/api_default.go
func (a *DefaultApiService) DeleteVessel
func (a *DefaultApiService) DepartVessel
func (a *DefaultApiService) GetTide
func (a *DefaultApiService) GetVessel
func (a *DefaultApiService) ListVessels
func (a *DefaultApiService) RegisterVessel
func (a *DefaultApiService) UpdateVessel
DepartVessel is a method of its own, which the entity model did not give you. Each method takes
a context.Context, so a hand-written tool handler can pass the request’s context through.
Check it worked
The test file builds the four servers and asserts on what MCP Inspector and the stand-in saw.
node --test generate.test.mjs
1..9
# tests 9
# suites 0
# pass 9
# fail 0
# cancelled 0
# skipped 0
# todo 0
# pass 9 covers every operation reaching the model, the five tool names and their hints, and
the two tools of the server built without the write switch. It covers a read-only call returning
the stand-in’s record, and a 404 arriving as a tool result with isError: true. It also covers an
id of ../tide reaching the API as ..%2Ftide, the v1 to v2 diff, and the two depart checks below.
When it goes wrong
An agent cannot discover the depart action. harbor_create with $action reaches the depart
endpoint, but no tool’s name, description, or schema mentions depart.
node inspect.mjs call v2 harbor_create entity=vessel 'data={"$action":"depart","id":"v1"}'
call harbor_create entity=vessel data={"$action":"depart","id":"v1"}
the API received POST /v1/vessels/v1/depart
isError: false
text: { "berth": null, "id": "v1", "name": "Maria Theresa", "status": "departed" }
Fix it in the model, not in go-mcp/. The
guide reference lets
.sdk/model/guide/guide.aontu switch the path off for vessel and give it an entity of its own.
guide: entity: vessel: path: "/vessels/{vesselId}/depart": active: false
guide: entity: departure: path: "/vessels/{vesselId}/depart": { rename: param: vesselId: id, op: create: method: POST }
node inspect.mjs list v2-guide
5 tools from bin/harbor-mcp-v2-guide
harbor_create destructiveHint=false entity: departure | vessel
harbor_list readOnlyHint=true entity: vessel
harbor_load readOnlyHint=true entity: tide | vessel
harbor_remove destructiveHint=true entity: vessel
harbor_update destructiveHint=true entity: vessel
departure is in the enum, and harbor_create with entity=departure and data={"id":"v1"}
reaches the same endpoint. The rename maps the path’s vesselId to the entity’s id, the field
that call sends.
An edit under go-mcp/ is lost on the next npm run generate, which rewrites tools.go. The
model, the guide, and project.aontu are the files that survive.
When not to do this
Do not reach for the sdkgen go-mcp target if you do not generate your SDK with sdkgen. Its value is the shared model, and adopting a generator for its MCP target alone buys a model to read with nothing to share it with. openapi-mcp-generator gives a stdio server in one command, with no model to read first.
Do not use it for an API whose operations are mostly actions. Each action needs a guide entry before an agent can see it, and Swagger Codegen’s one-method-per-operation client keeps every action by name.
Do not turn on the write tools for an agent that only reads. The default is off for that reason.
Choose Fern when you want the server hosted at a URL with no binary to ship, and an account is acceptable to your organization.
Related how-tos
Last verified
Verified 2026-11-20 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, the Go MCP SDK v1.6.0,
@modelcontextprotocol/inspector 2.16.0, and Swagger Codegen 3.0.85. Every output block is what
the command preceding it printed. The four sdkgen runs and the Swagger Codegen run happened once,
and their output is committed; the servers are built from it on each check. Fern was not run. Its options come from its documentation.
Footnotes
-
The list tool’s result carries the records twice, as text and as
structuredContent, and the structured copy is a JSON array. The 2025-11-25 revision says structured content is returned as a JSON object. The 2026-07-28 revision widens that to a JSON value, array included, so the same bytes are out of step with one revision and in step with the next. ↩︎ Back to text -
The list is served by Swagger’s own hosted generator at generator3.swagger.io, and it runs from
csharptotypescript-fetch, with three generations of Swift along the way,swift3,swift4, andswift5. The project’s about page describes the tool as generating API client libraries, server stubs, and documentation. ↩︎ Back to text