How-to › Expose your API to agents

How to generate an MCP server from a semantic model with sdkgen#

Generate a Go MCP server from the model behind your sdkgen SDK, and check its tools with MCP Inspector before and after a spec change.

Audience
API producer
Level
advanced
Topic
Build an MCP server
Languages
Go and TypeScript
Verified

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
Fern MCP generatorYou want a hosted server at a stable URL, with tool names set per operationA Fern account to deploy, and a hosted service between the agent and your APIYou must run the server yourself, offline, or without a vendor account
openapi-mcp-generatorOne TypeScript server, one tool per operation, filtered by tag or operationIdA second generator beside your SDK’s, so the two vocabularies drift apartYour SDK and server should share one set of names
sdkgen go-mcp targetYou generate the SDK with sdkgen and want the server from the same modelTools per operation with an entity argument, and a classification you must read before you trust itThe API is a set of actions, which the entity model folds away
Swagger Codegen with a hand-written serverA generated Go client exists and you want each tool written by handNo MCP target, so every tool, schema, and description is yours to write and keepMore 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.

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

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

  2. The list is served by Swagger’s own hosted generator at generator3.swagger.io, and it runs from csharp to typescript-fetch, with three generations of Swift along the way, swift3, swift4, and swift5. The project’s about page describes the tool as generating API client libraries, server stubs, and documentation. ↩︎ 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.