How-to › Describe your API

How to verify an SDK, CLI and MCP server share one model version#

Fail a release when its SDK, CLI and MCP server came from different specs or models, with a check that reads each surface's generated code, not only a checksum.

Audience
Agent builder
Level
intermediate
Topic
Extract a semantic model from a spec
Languages
TypeScript and Go
Verified

A teammate tries a guide edit that hides authors from agents, regenerates, and commits only go-mcp/. The OpenAPI document never changed, so the spec checksum in CI still matches. The release then ships a TypeScript SDK and a Go CLI that know author beside an MCP server whose tools refuse it.

What you get

You will end up with a release check that reads the entity list out of each generated surface and fails when one disagrees with the committed model. This is for you if one project generates an SDK, a CLI and an MCP server for agents, and they ship together.

Short answer

Record the spec hash each surface was generated from, and also read the entity list each generated surface carries and compare it with the committed model. A spec checksum catches a surface built from an older spec, but passes one rebuilt after a local model edit. sdkgen’s doctor exits 0 on both, check-drift fails both, and Hey API and openapi-typescript need a header stamp or --check.

You will need

Node 22 or later, Go 1.24 or later to build the MCP server, and a project that generates more than one surface. Verified 2026-11-21 against Node 22.23.5, Go 1.24.7, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4, @hey-api/openapi-ts 0.99.0 and openapi-typescript 7.13.0. The sample holds a Bookshelf document in two versions: api-v1.json with books, and api-v2.json, which adds /authors.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
A checksum recorded in CI artifactsAny generator, with each surface built by its own jobIt sees the spec alone, so a model or guide edit passes, and it names no causeThe generator reads files beside the spec
Hey API output header stampA Hey API client, where output.header writes a line into every fileA stamp you design and a script you keep, and it records only what you hashThe spec is the only input, and openapi-typescript is already in use
openapi-typescript —checkTypes from openapi-typescript, checked against the spec in CICovers its own output alone, and answers yes or no with no reasonSeveral generators feed one release
sdkgen check-driftAn sdkgen project, before a releaseDeletes and regenerates every target, and needs the .sdk toolchain installedYou need a check that runs in seconds on every push
voxgig-sdkgen doctorChecking the .sdk copies against the scaffoldIt never reads generated output, so it passed every release hereThe question is which model a surface came from

Voxgig maintains sdkgen. This page compares two of its commands with a checksum and the checks of two other generators, and sdkgen is not the recommendation.

The checksum works for every generator and says nothing about why a surface differs. The two generator-aware rows know their own output: openapi-typescript compares its types, and check-drift compares every sdkgen target. Neither looks across tools, so the model check below reads the surfaces directly.

Build three releases from one project

generate.sh scaffolds one project from api-v2.json with four targets and commits it as release:

cp "$here/api-v2.json" api.json
npx --yes @voxgig/create-sdkgen@0.31.9 bookshelf --def api.json --target ts --target go --target go-cli --target go-mcp > scaffold.log 2>&1
(cd bookshelf-sdk/.sdk && npm run generate > ../../generate.log 2>&1)

Two copies of it then regenerate every target, and the script puts back only their go-mcp/tools.go. old-spec swaps in api-v1.json first. model-only appends guide-edit.aontu, which switches the author entity off, and leaves that edit out of the commit. For each surface the script writes the artifact its CI job would: the sha256 of the spec it generated from.

No surface carries a version on its own. The model holds main.kit.info.version, 1.1.0, but a search of ts/, go/, go-cli/ and go-mcp/ found that version and the spec’s hash in no file. A check therefore has to read the surfaces themselves.

Run four checks on each release

verify.mjs runs the checksum and the model check on each release and reads the doctor and check-drift runs that generate.sh recorded:

node verify.mjs
release     doctor  spec checksum  surfaces vs model  check-drift
release     exit 0  ok             ok                 exit 0
old-spec    exit 0  FAIL go-mcp    FAIL go-mcp        exit 1 go-mcp/tools.go
model-only  exit 0  ok             FAIL go-mcp        exit 1 go-mcp/tools.go

The checksum caught the older spec and passed the model edit, which is the pitfall in one row. doctor passed all three, because it compares the copies under .sdk/ with the scaffold and never opens go-mcp/. check-drift failed both bad releases and named the file. @voxgig/sdkgen 4.45.0 with @voxgig/apidef 8.33.1 gave the same doctor and check-drift results on all three releases.

Read the entity list out of each surface

checks.mjs reads three files: the entity block in the SDK’s ts/src/Config.ts, the case lines in go-cli/words.go, and the enum each tool in go-mcp/tools.go passes to entitySchema. A reader that finds nothing throws, so a changed template fails the check instead of passing it.

  'go-mcp': (dir) => {
    const lists = [...read(dir, 'go-mcp/tools.go').matchAll(/InputSchema: entitySchema\[\w+\]\(([^)]*)\)/g)]
    if (lists.length === 0) throw new Error('no tool schemas in go-mcp/tools.go')
    const sets = lists.map((m) => sorted([...m[1].matchAll(/"([a-z0-9_]+)"/g)].map((x) => x[1])).join(' '))
    if (new Set(sets).size !== 1) throw new Error(`go-mcp tools disagree with each other: ${sets.join(' | ')}`)
    return found(sets[0].split(' ').filter(Boolean), 'go-mcp/tools.go')
  },
node verify.mjs generated/model-only
generated/model-only: model has author, book
  ts SDK  ok    author, book
  go-cli  ok    author, book
  go-mcp  FAIL  book

The command exits 1. generate.sh also built each MCP server and sent it tools/list over stdio; both of its tools answered with an entity enum of book alone, and a test holds the reader to those answers.1

Stamp the Hey API and openapi-typescript clients

Hey API and openapi-typescript generate from the spec alone, so the spec hash is the whole question for them. Hey API’s output.header option takes a function of the default header, and this configuration adds the hash:

export default {
  input: spec,
  output: {
    path: process.env.OUT ?? 'client',
    header: (ctx) => [...ctx.defaultValue, `// openapi-sha256: ${sha256}`],
  },
}

openapi-typescript needs no stamp: its --check flag regenerates in memory, compares with the file, and exits 1 when they differ, writing nothing. stamps.mjs runs both against the release spec, with a client from each document:

node stamps.mjs
release spec api-v2.json, sha256 be941341ba80
  Hey API from api-v2.json             ok    4 files, be941341ba80
  openapi-typescript from api-v2.json  ok    --check exit 0
  Hey API from api-v1.json             FAIL  stamp 554e49a1d327, spec be941341ba80
  openapi-typescript from api-v1.json  FAIL  --check exit 1

Check it worked

Ten tests cover the table, the readers, the recorded tools/list answers and both stamps:

node --test verify.test.mjs
1..10
# tests 10
# suites 0
# pass 10
# fail 0
# cancelled 0
# skipped 0
# todo 0

Four of them break copies of Config.ts, tools.go, the artifacts and the Hey API files, and expect each check to throw or fail. One drops the old-spec server into the good release on purpose, and the model check names go-mcp.

When it goes wrong

doctor reports .sdk matches the scaffold and the MCP server is still wrong. It compares only the copies target add wrote under .sdk/. Gate the release on check-drift, or on a check that reads the output.

check-drift reports M go-mcp/tools.go without saying why the file changed. It names the file, not the cause. The model check names the surface and the missing entity, and the artifact hash says whether the spec moved.

A release passes the checksum with a surface’s artifact missing. A check that compares only the artifacts it finds cannot see the one that is absent. checksum() names the surfaces a release ships, and fails one with no artifact, a hash that is empty or malformed, or a file that names another surface.

A Hey API file has no stamp. A file written by hand, or by an older configuration, has no header line. stamps.mjs reads every file under the output, subdirectories included, and fails an unstamped one rather than skipping it.

When not to do this

Do not rely on a spec checksum alone for a generator that reads anything beside the spec. sdkgen reads the guide and the project overlay, so a model edit leaves the hash unchanged.

Do not run check-drift on every push in a large project. It deletes and regenerates every target, work the script’s own comment puts at minutes. Run it before a release, and run the model check on every push.

Do not take doctor’s exit 0 as evidence about generated output. Hey API is the better choice when the release is one TypeScript client: one header option and a short script cover it. openapi-typescript’s --check suits a team that ships types only, because it needs no script at all.

Last verified

Verified 2026-11-21 against Node 22.23.5, Go 1.24.7, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4, @hey-api/openapi-ts 0.99.0, openapi-typescript 7.13.0 and TypeScript 5.9.3. Every output block is what the command preceding it printed. The scaffold, the three generations, doctor, check-drift on 4.44.3 and 4.45.0, the MCP server builds and the Hey API runs happened once, in generate.sh, and their output is committed. The commands here read that output, and stamps.mjs runs openapi-typescript’s --check live.

Footnotes

  1. The enum is plain JSON Schema: the value must be an array, should have at least one element, and its elements should be unique. A server with one entity fewer still satisfies all three, so validating the tool schemas cannot find the gap. ↩︎ 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.