How-to › Expose your API to agents

How to add a custom tool to a generated MCP server without a fork#

Add a create-and-wait tool to an sdkgen Go MCP server through a project-owned component, and prove it is still registered after a spec change and a regeneration.

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

Read first: Generate an MCP server from a semantic model with sdkgen

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
Forking the generator outputOne release, then the server is maintained by handEvery later spec change merged by hand, because the next generate rewrites tools.goThe document still changes
OpenAPI GeneratorYou want a typed client and will write the whole MCP server over itNo MCP generator, so every tool, schema and description is yours, generated or customYou want the tools for the API’s operations generated
sdkgen model and component customizationAn sdkgen project whose custom tool calls the generated SDKA component, a fragment and an edited copy to keep, and the generated helpers it reuses can changeThe tool needs code the Go server cannot hold
Speakeasy MCP extensions and OpenAPI overlaysA Speakeasy TypeScript MCP server, with a file of extensions it keepsAn account to run the CLI, and a TypeScript server rather than GoYou cannot or will not create a Speakeasy account
A wrapper server that proxies the generated oneThe custom tools change on a different clock from the APIA second process in the path, and generator improvements reach only the tools it forwardsOne 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.

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

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

  2. In the command’s own help, doctor exits 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. Under main: kit: copies: 'overwrite' the same edited fragment was reported as forked, with exit 1. ↩︎ 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.