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

Source: https://voxgig.com/howto/generate-an-mcp-server-from-a-semantic-model

- Audience: api-producer
- Level: advanced
- Languages: go, typescript
- Verified: 2026-11-20
- Published: 2026-11-20

## 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](https://github.com/modelcontextprotocol/go-sdk).

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Fern MCP generator](https://buildwithfern.com/learn/mcp-generator/get-started/quickstart) | 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](https://github.com/harsha-iiiv/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](https://github.com/voxgig/sdkgen/blob/main/docs/reference/model.md) | 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](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/about/) | 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.

```bash title="generate.sh"
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](https://github.com/voxgig/sdkgen/blob/main/docs/reference/model.md) 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
bash build.sh
```

```text output
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.

```bash
node model.mjs v2
```

```text output
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](https://github.com/modelcontextprotocol/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.

```bash
node inspect.mjs list v2
```

```text output
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`.

```bash
node inspect.mjs call v2 harbor_load entity=vessel 'query={"id":"v1"}'
```

```text output
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.

```bash
node inspect.mjs diff v1 v2
```

```text output
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](https://buildwithfern.com/learn/mcp-generator/get-started/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.

```bash
grep -o '^func (a \*DefaultApiService) [A-Za-z]*' swagger-codegen/api_default.go
```

```text output
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.

```bash
node --test generate.test.mjs
```

```text output
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`.

```bash
node inspect.mjs call v2 harbor_create entity=vessel 'data={"$action":"depart","id":"v1"}'
```

```text output
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](https://github.com/voxgig/apidef/blob/main/docs/reference/guide.md) lets
`.sdk/model/guide/guide.aontu` switch the path off for `vessel` and give it an entity of its own.

```aontu title="guide.aontu"
guide: entity: vessel: path: "/vessels/{vesselId}/depart": active: false
guide: entity: departure: path: "/vessels/{vesselId}/depart": { rename: param: vesselId: id, op: create: method: POST }
```

```bash
node inspect.mjs list v2-guide
```

```text output
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

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

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

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

- [Name tools so an agent picks the right one from fifty](/howto/name-tools-so-agents-pick-the-right-one)

- [Derive MCP tool names and schemas from a semantic model](/howto/derive-tool-schemas-from-a-semantic-model)

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

[^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](https://modelcontextprotocol.io/specification/2025-11-25/server/tools) says
structured content is returned as a JSON object. The
[2026-07-28 revision](https://modelcontextprotocol.io/specification/2026-07-28/server/tools)
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.

[^2]: The list is served by Swagger's own hosted generator at
[generator3.swagger.io](https://generator3.swagger.io/api/client/V3), 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](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/about/)
describes the tool as generating API client libraries, server stubs, and documentation.