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

Source: https://voxgig.com/howto/add-a-custom-tool-to-a-generated-server

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

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

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Forking the generator output](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp) | 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](https://openapi-generator.tech/docs/generators/) | 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](https://github.com/voxgig/sdkgen/blob/main/docs/reference/model.md) | 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](https://www.speakeasy.com/docs/standalone-mcp/custom-resources) | 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](https://github.com/modelcontextprotocol/typescript-sdk) | 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](https://github.com/voxgig/sdkgen/blob/main/docs/reference/model.md) 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.

```ts title="sdk/src/cmp/go-mcp/CustomTools_go-mcp.ts"
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:

```go title="sdk/src/cmp/go-mcp/fragment/custom_tools.fragment.go"
	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`:

```ts title="sdk/src/Root.ts"
  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:

```aontu title="sdk/model/custom-tool.aontu"
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](https://github.com/voxgig/sdkgen/blob/main/docs/explanation/copies-merge.md)
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`.

```bash title="generate.sh"
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
bash build.sh
```

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

```bash
node tools.mjs list
```

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

```bash
node tools.mjs call api 1.2.0
```

```text output
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](https://openapi-generator.tech/docs/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:

```bash
grep -o '^func (a \*DefaultAPIService) [A-Za-z]*' generated/openapi-generator-go/api_default.go | grep -v Execute | sort
```

```text output
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](https://openapi-generator.tech/docs/customization/) 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](https://www.speakeasy.com/docs/standalone-mcp/custom-resources) says
to run `speakeasy run` after adding it. The generated tools themselves are shaped with
[`x-speakeasy-mcp`](https://www.speakeasy.com/docs/standalone-mcp/customize-tools) on each
operation, which an overlay can add without editing the document.
[Custom code regions](https://www.speakeasy.com/docs/sdks/customize/code/code-regions/overview)
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.

```bash
node --test custom-tool.test.mjs
```

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

```bash
cat doctor.txt
```

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

- [Generate an MCP server from a semantic model with sdkgen](/howto/generate-an-mcp-server-from-a-semantic-model)

- [Build an MCP server in Go over an existing HTTP client](/howto/build-an-mcp-server-in-go)

- [Keep generated files out of a coding agent's edits](/howto/keep-generated-files-out-of-agent-edits)

- [Keep an agent informed while an MCP tool runs for minutes](/howto/report-progress-from-a-long-running-tool)

- [Unit test MCP tool handlers without starting a server](/howto/unit-test-mcp-tool-handlers)

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

[^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](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle)
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.

[^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](https://github.com/voxgig/sdkgen/blob/main/docs/reference/cli.md) 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.