An agent deploying through your generated MCP server calls its create tool, then polls
deploy_load in a loop of its own, spending a turn on each poll. The rule for when to stop lives
in a prompt. You add a create_and_wait tool to go-mcp/tools.go, and the next
npm run generate removes it without a word.
What you get
You will end up with a Go MCP server that registers a create-and-wait tool beside its generated ones. The tool survives a spec change, a regeneration and a re-add of the target. This is for you if you generate the server with sdkgen and an agent needs a tool the document cannot express.
Short answer
Write the tool as a project-owned sdkgen component, .sdk/src/cmp/go-mcp/CustomTools_go-mcp.ts,
wire it into .sdk/src/Root.ts with registerComponent, and add one call to the project’s copy
of main.fragment.go. Put the tool’s settings in project.aontu. npm run generate then writes
custom_tools.go beside the generated tools on every run, and a re-add of the target merges its
own changes into the edited copy.
You will need
Node 22 or later, Go 1.25 or a Go that can fetch it, and an sdkgen project with the go and
go-mcp targets, as generating an MCP server from a semantic model
sets up. The document here, api.v1.json, is a Deploy API whose POST /deployments answers with
status: pending. api.v2.json adds GET /services. The server is built on the
Go MCP SDK.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Forking the generator output | One release, then the server is maintained by hand | Every later spec change merged by hand, because the next generate rewrites tools.go | The document still changes |
| OpenAPI Generator | You want a typed client and will write the whole MCP server over it | No MCP generator, so every tool, schema and description is yours, generated or custom | You want the tools for the API’s operations generated |
| sdkgen model and component customization | An sdkgen project whose custom tool calls the generated SDK | A component, a fragment and an edited copy to keep, and the generated helpers it reuses can change | The tool needs code the Go server cannot hold |
| Speakeasy MCP extensions and OpenAPI overlays | A Speakeasy TypeScript MCP server, with a file of extensions it keeps | An account to run the CLI, and a TypeScript server rather than Go | You cannot or will not create a Speakeasy account |
| A wrapper server that proxies the generated one | The custom tools change on a different clock from the API | A second process in the path, and generator improvements reach only the tools it forwards | One server is enough and the generator can hold the tool |
Voxgig maintains sdkgen, the subject of this page. Its row says when another option fits better.
The sdkgen component and Speakeasy’s extension file both keep the tool inside the generated server, so it inherits each regeneration and can break when a generated helper changes. The wrapper is isolated from both, at the price of a second process. A fork costs every future spec change, and OpenAPI Generator costs the generated tools themselves.
Write the tool as a component the project owns
The model reference names
the lever: a component registered with registerComponent('X') is loaded from
.sdk/src/cmp/<target>/X_<target>.ts. This one writes custom_tools.go from a fragment beside
it, with the tool’s name and timings from the model.
const CustomTools = cmp(function CustomTools(props: any) {
const { target } = props
const { model } = props.ctx$
const tool = target.custom?.createAndWait
if (null == tool) {
return
}
const FRAGMENT = Path.normalize(__dirname + '/../../../src/cmp/go-mcp/fragment')
File({ name: 'custom_tools.go' }, () => {
Fragment({
from: Path.join(FRAGMENT, 'custom_tools.fragment.go'),
The fragment is ordinary Go. It creates the deployment through the generated SDK, then loads it
until the status is active or failed, or the deadline passes:
for {
status, _ := record["status"].(string)
switch status {
case "active":
body, err := json.MarshalIndent(map[string]any{"deployment": record, "polls": polls}, "", " ")
if err != nil {
return toolError(fmt.Sprintf("marshal: %v", err))
}
return &mcp.CallToolResult{Content: []mcp.Content{&mcp.TextContent{Text: string(body)}}}, nil, nil
case "failed":
return toolError(fmt.Sprintf("deployment %s failed after %d polls", id, polls))
}
select {
case <-ctx.Done():
return toolError(fmt.Sprintf("deployment %s still %q after %s", id, status, waitTimeout))
case <-time.After(waitPoll):
}
toolError, extractData and hint are helpers from the generated tools.go, which saves code
and couples the fragment to them. The Go compiler reports it if a regeneration renames one. The
generated SDK’s operations take no context.Context, so the deadline is checked between polls.
Wire it in and give it settings
Three small edits connect it. .sdk/src/Root.ts, the project’s wiring, calls the component after
each target’s Main:
Main({ target })
// Project-owned: .sdk/src/cmp/<target>/CustomTools_<target>.ts, where one exists.
CustomTools({ target })
The generated main.go calls registerTools and nothing else, so the project’s copy of
main.fragment.go gains one line after it, registerCustomTools(server, client). The settings go
in the project overlay, which the model reference says carries over every update:
main: kit: target: 'go-mcp': custom: createAndWait: {
name: 'deploy_create_and_wait'
description: 'Create a Deploy deployment and wait until it is active. Args: service, version. Returns the active deployment and the number of polls as JSON, or an error if it fails or does not become active in time.'
pollMs: 100
timeoutMs: 1500
}
Regenerate after the spec change
generate.sh swaps in api.v2.json, regenerates, re-adds the target, and regenerates again. The
copies reference
says an add merges the incoming copy into one the project changed, and the run logged
merged the incoming copy into 1 locally changed file(s) for main.fragment.go.
cp "$here/api.v2.json" def/api.json
npm run generate # v2
npx voxgig-sdkgen target add go-mcp
npm run generate # v2, after the re-add
build.sh builds the server from the committed v2 output.
bash build.sh
deploy-mcp
MCP Inspector is the interactive check. tools.mjs does the same job in a script: it starts the
binary over stdio with mcp-client.mjs, initializes, and sends tools/list.1
node tools.mjs list
3 tools from bin/deploy-mcp
deploy_create_and_wait destructiveHint=false args: service, version
deploy_list readOnlyHint=true args: entity, query
deploy_load readOnlyHint=true args: entity, query
The custom tool is still listed after the regeneration, and deploy_list gained the service
entity that v2 added. A call reaches the stand-in through the generated SDK:
node tools.mjs call api 1.2.0
call deploy_create_and_wait service=api version=1.2.0
the API received POST /v1/deployments, GET /v1/deployments/d1, GET /v1/deployments/d1
isError: false
text: { "deployment": { "id": "d1", "service": "api", "status": "active", "version": "1.2.0" }, "polls": 2 }
Add the same tool with OpenAPI Generator and Speakeasy
OpenAPI Generator 7.27.0 has no MCP server among its generators. Its Go client gives you one method per operation, and the create-and-wait tool is a hand-written handler over two of them, inside a server you write with the Go MCP SDK:
grep -o '^func (a \*DefaultAPIService) [A-Za-z]*' generated/openapi-generator-go/api_default.go | grep -v Execute | sort
func (a *DefaultAPIService) CreateDeployment
func (a *DefaultAPIService) GetDeployment
func (a *DefaultAPIService) ListDeployments
func (a *DefaultAPIService) ListServices
Regeneration keeps a server written that way, because it lives outside the generated client, and
.openapi-generator-ignore protects any file you place inside it, as its
customization page describes.
Speakeasy generates a TypeScript MCP server and reads a file you add, server.extensions.ts in
the mcp-server directory, whose registerMCPExtensions(register) calls register.tool(...).
Its custom resources page says
to run speakeasy run after adding it. The generated tools themselves are shaped with
x-speakeasy-mcp on each
operation, which an overlay can add without editing the document.
Custom code regions
apply to its Java, Python and TypeScript SDKs rather than the MCP server, and that page lists them
for Enterprise users only.
Check it worked
Ten tests run against the built binary and the committed output.
node --test custom-tool.test.mjs
1..10
# tests 10
# suites 0
# pass 10
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 2121.213847
One compares custom_tools.go and main.go across the v1 and v2 runs, byte for byte, and expects
tools.go to differ. Others call the tool for a deployment that fails and one that never turns
active, refuse an empty version before any request, and send ../services as an id, which
reaches the stand-in as ..%2Fservices. One lists the service entity that v2 added.
When it goes wrong
The custom tool vanishes after a generate, and doctor raised nothing. The edit was made under
go-mcp/, which the generator owns. generate.sh recorded what voxgig-sdkgen doctor said
about both shapes:
cat doctor.txt
== doctor after the customization
INFO: sdkgen doctor-finding CUSTOMIZED (an add merges its updates into it): src/cmp/go-mcp/fragment/main.fragment.go
INFO: sdkgen doctor-finding additive (project-owned, not drift): src/cmp/go-mcp/CustomTools_go-mcp.ts
INFO: sdkgen doctor-finding additive (project-owned, not drift): src/cmp/go-mcp/fragment/custom_tools.fragment.go
INFO: sdkgen doctor-end .sdk matches the scaffold (2 additive, 1 customized)
exit 0
== doctor after a hand edit to go-mcp/tools.go
INFO: sdkgen doctor-finding CUSTOMIZED (an add merges its updates into it): src/cmp/go-mcp/fragment/main.fragment.go
INFO: sdkgen doctor-finding additive (project-owned, not drift): src/cmp/go-mcp/CustomTools_go-mcp.ts
INFO: sdkgen doctor-finding additive (project-owned, not drift): src/cmp/go-mcp/fragment/custom_tools.fragment.go
INFO: sdkgen doctor-end .sdk matches the scaffold (2 additive, 1 customized)
exit 0
hand edit still in tools.go after generate: 0
doctor compares .sdk/ with the scaffold and never reads go-mcp/, so the hand edit passes it
and the next generate removes it. Gate on the tool list instead: a CI step that regenerates,
builds, and fails when deploy_create_and_wait is missing.2
The re-add stops with a conflict. The incoming main.fragment.go changed the same lines as yours.
Fold the change in by hand and re-run with --keep, as the copies reference describes.
When not to do this
Do not build a custom tool in sdkgen for logic the agent could get from two generated tools and a sentence in their descriptions. Each component, fragment and edited copy is code you maintain through every toolchain upgrade.
Do not reuse generated helpers you cannot afford to lose. toolError and extractData are not a
published interface, and a rename stops the build.
Do not put the tool in sdkgen when it needs secrets, state or a language the Go server lacks. A wrapper server holds those, and never inherits generator changes. OpenAPI Generator is the better fit when you would rather write every tool and want only a typed client underneath. Speakeasy fits when your server is TypeScript and the extension file suits you.
Related how-tos
Last verified
Verified 2026-11-21 against Node 22.23.5, Go 1.25.0, @voxgig/create-sdkgen 0.31.9,
@voxgig/sdkgen 4.44.3, the Go MCP SDK v1.6.0, and OpenAPI Generator 7.27.0. Every output block
is what the command preceding it printed. The sdkgen runs and the OpenAPI Generator run happened
once in generate.sh, and their output is committed; doctor.txt is that run’s record. sdkgen
4.45.0 generated the same three files and gave doctor the same verdict. Speakeasy was not run, and what this page says
about its MCP extension is read from its documentation.
Footnotes
-
The client asks for protocol revision 2025-11-25. Asked for 2026-07-28 instead, the server built on go-sdk v1.6.0 answered with 2025-11-25. The lifecycle section of that revision permits it: a server that lacks the requested version responds with another it supports, and a client that cannot use that one should disconnect. ↩︎ Back to text
-
In the command’s own help,
doctorexits non-zero “when a component is forked, a template master edited, or a stale file left behind” with no mention of merge mode. The CLI reference adds the exception for merge mode, the default, in which a changed copy is reported as customized and passes. Undermain: kit: copies: 'overwrite'the same edited fragment was reported as forked, with exit 1. ↩︎ Back to text