# How to decide whether to generate or hand-write an MCP server

> Score generation, hand writing, and a facade over a generated client on spec quality, operation count, task shape, and change rate, from files you commit.

Source: https://voxgig.com/howto/generate-or-hand-write-an-mcp-server

- Audience: api-producer
- Level: beginner
- Verified: 2026-11-22
- Published: 2026-11-22

## Short answer

Score each way of building the MCP server from four inputs. They are the quality of the OpenAPI document, the operation count, how many of the agent's tasks need one operation, and how often the document changes. Count the tools each candidate shows an agent per turn, not the endpoints. On the Clinic API here a hand-written facade over a generated client scores highest, and a per-endpoint generator wins once upkeep outweighs curation.

---
## You will need

Node 22 or later, an API you own, and a working understanding of
[MCP tools](https://modelcontextprotocol.io/specification/2026-07-28/server/tools). The rubric
reads three files about the API: its OpenAPI document, the agent's tasks, and its changelog. The
Clinic API here has fourteen operations, and `make-large.mjs` grows it to 104 with eighteen more
resource families. The hand-written server is JavaScript, on the official TypeScript SDK. Verified
2026-11-22 against Node 22.23.5.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Hand-written server on the official TypeScript MCP SDK](https://modelcontextprotocol.io/docs/2026-07-28/develop/build-server) | A few tools shaped like the agent's tasks, over a client you also own | A handler, schema, and description per tool, edited by hand on every change to the API | The document changes every week and nobody owns the tools |
| [Kiota client behind a hand-written facade](https://learn.microsoft.com/en-us/openapi/kiota/overview) | You already ship Kiota clients and want the facade in a language Kiota targets | Kiota writes a client, not a server, so every tool is yours to write | You want any tool generated for you |
| [openapi-mcp-generator](https://github.com/harsha-iiiv/openapi-mcp-generator) | A TypeScript server with one typed tool per operation, regenerated in seconds | One tool per endpoint, so the agent's choice grows with the document | The tasks span several operations, or the document has a hundred |
| [sdkgen go-mcp target](https://github.com/voxgig/sdkgen/blob/main/docs/reference/model.md) | You generate the SDK with sdkgen and want a server from the same model | Read-only until configured, a free-form query argument, and descriptions from a template | The agent writes, or needs the parameters named in the schema |
| [Speakeasy Standalone MCP](https://www.speakeasy.com/docs/standalone-mcp/build-server) | You use Speakeasy and want curation in the document with `x-speakeasy-mcp` | An account, a target graded Beta, and extensions written into the document | You cannot send the document to a vendor |

Voxgig maintains sdkgen, which is one of the five rows here and not the recommendation.

The generators trade curation for sync. openapi-mcp-generator follows the document exactly, so its
tool count is the operation count. sdkgen's go-mcp folds operations into five verb tools with the
entity as an argument, so its count stays flat and its schemas say less. A facade costs handlers,
and each one is written against a client that regenerates.

## Write down the inputs and the weights

The rubric reads `tasks.json`, the agent's work, one entry per task with the operations it needs,
and `changes.json`, a release list from the document's changelog. Spec quality and operation count
come from `api.json` itself. The weights are a team's opinion, so they live in a file:

```json title="weights.json"
{
  "team": "default: an agent that books and moves appointments",
  "toolBudget": 10,
  "editsBudgetPerQuarter": 3,
  "facadeBreaks": ["renamed-field", "renamed-parameter", "removed-field", "removed-operation"],
  "weights": { "toolLoad": 3, "taskFit": 3, "descriptions": 1, "schemas": 2, "upkeep": 2 }
}
```

`toolLoad` is the tool budget over the tools a server lists. `taskFit` averages one over the
fewest calls each task takes, and zero for a task the server cannot do. `descriptions` is the
share of generated tools whose description carries the operation's summary, and 1 for tools
written by hand. `schemas` is the
share of tools with no free-form argument. `upkeep` falls with the hand edits a quarter of
changes would need. Hand-written code needs an edit for every change to an operation it calls. A facade over a regenerated
client needs one only for a rename or a removal.

## Score the candidates on your document

`score.mjs` reads the tool lists that `record.sh` captured from each generated server over stdio,
and the facade's own tool table:

```bash
node score.mjs api.json
```

```text output
api.json: 14 operations, spec quality 0.89, 5 tasks (0.60 need one operation), 4.01 changes a quarter
weights (weights.json): toolLoad 3, taskFit 3, descriptions 1, schemas 2, upkeep 2; tool budget 10
                         tools  tasks  calls       edits/q  toolLoad     taskFit      descriptions schemas      upkeep       score
openapi-mcp-generator       14    5/5  3 4 1 1 1      0.00  0.71         0.72         0.79         1.00         1.00         83
sdkgen go-mcp, stock         2    2/5  - - - 1 1      0.00  1.00         0.40         0.00         0.00         1.00         56
sdkgen go-mcp, write on      5    5/5  3 4 1 1 1      0.00  1.00         0.72         0.00         0.00         1.00         65
hand-written, fetch          6    5/5  2 2 1 1 1      2.51  1.00         0.80         1.00         1.00         0.16         79
facade over an SDK           6    5/5  2 2 1 1 1      1.00  1.00         0.80         1.00         1.00         0.67         88
highest: facade over an SDK (facade)
```

The stock go-mcp server lists two read-only tools, so three of the five tasks, the ones that
write, are out of its reach. With `tool: write: true` it covers all five, but its `query`
argument is an open object that names no parameter. Both servers built again on 4.45.0 with
apidef 8.33.1 listed the same tools. The hand-written server and the facade expose
the same six tools, and the changelog separates them: 2.51 hand edits a quarter against 1.00.

## Score again when the document grows

Run the same rubric on the 104-operation document. The tasks did not change:

```bash
node score.mjs api-large.json
```

```text output
api-large.json: 104 operations, spec quality 0.86, 5 tasks (0.60 need one operation), 4.01 changes a quarter
weights (weights.json): toolLoad 3, taskFit 3, descriptions 1, schemas 2, upkeep 2; tool budget 10
                         tools  tasks  calls       edits/q  toolLoad     taskFit      descriptions schemas      upkeep       score
openapi-mcp-generator      104    5/5  3 4 1 1 1      0.00  0.10         0.72         0.97         1.00         1.00         67
sdkgen go-mcp, stock         2    2/5  - - - 1 1      0.00  1.00         0.40         0.00         0.00         1.00         56
sdkgen go-mcp, write on      5    5/5  3 4 1 1 1      0.00  1.00         0.72         0.00         0.00         1.00         65
hand-written, fetch          6    5/5  2 2 1 1 1      2.51  1.00         0.80         1.00         1.00         0.16         79
facade over an SDK           6    5/5  2 2 1 1 1      1.00  1.00         0.80         1.00         1.00         0.67         88
highest: facade over an SDK (facade)
```

Only the per-endpoint row moved. go-mcp still lists five tools, because its count follows the
verbs, and its `list` tool's entity argument now takes one of 23 values. The operation count
decides nothing by itself: it is the tools an agent chooses between per turn that changed.[^1]

## Build the facade the score picked

`facade.mjs` registers six tools on `McpServer` from `@modelcontextprotocol/server`.[^2] Each one
calls a backend, so the same tools run over the sdkgen SDK, the Kiota client, or `fetch`:

```js title="facade.mjs"
  server.registerTool('find_open_slots', {
    description: 'Open appointment slots with practitioners of one specialty, earliest first. Use it before booking or moving an appointment.',
    inputSchema: z.object({
      specialty: z.string().min(1).describe('A specialty such as physiotherapy or dermatology'),
      from: z.iso.datetime().optional().describe('Only slots that start at or after this time, ISO 8601'),
    }),
    annotations: READ,
  }, guarded(async ({ specialty, from }) => {
    const people = await backend.listPractitioners({ specialty })
    const slots = []
    for (const p of people) {
      for (const s of await backend.listSlots({ practitioner_id: p.id, from })) {
        slots.push({ slot_id: s.id, start: s.start, practitioner: p.name })
      }
    }
    slots.sort((a, b) => (a.start < b.start ? -1 : a.start > b.start ? 1 : 0))
    return json({ slots })
  }))
```

`demo.mjs` connects an MCP client over the SDK's in-memory transport and books, moves, and then
double-books a slot:

```bash
node demo.mjs
```

```text output
facade over the sdkgen SDK: 6 tools: find_open_slots, book_appointment, reschedule_appointment, cancel_appointment, patient_balance, find_patient
  find_open_slots {"specialty":"physiotherapy"}
    -> {"slots":[{"slot_id":"s2","start":"2026-12-01T09:00:00Z","practitioner":"Chen Li"},{"slot_id":"s1","start":"2026-12-01T10:00:00Z","practitioner":"Ana Ruiz"},{"slot_id":"s4","start":"2026-12-02T09:00:00Z","practitioner":"Ana Ruiz"}]}
    requests: GET /v2/practitioners?specialty=physiotherapy, GET /v2/slots?practitioner_id=pr1, GET /v2/slots?practitioner_id=pr3
  book_appointment {"patient_id":"p1","slot_id":"s2"}
    -> {"id":"a1","patient_id":"p1","slot_id":"s2","start":"2026-12-01T09:00:00Z","status":"booked"}
    requests: POST /v2/appointments
  reschedule_appointment {"appointment_id":"a1","slot_id":"s1"}
    -> {"id":"a1","patient_id":"p1","slot_id":"s1","start":"2026-12-01T10:00:00Z","status":"booked"}
    requests: GET /v2/appointments/a1, PATCH /v2/appointments/a1
  book_appointment {"patient_id":"p1","slot_id":"s1"}
    -> {"error":"the Clinic API refused the call: ClinicSDK: create: request: 409: Conflict"}
    requests: POST /v2/appointments
the same two calls over the other backends:
  Kiota client: s2 s1 s4, booked s2, 4 requests
  hand-written fetch: s2 s1 s4, booked s2, 4 requests
```

One tool call made three requests, which is the curation a generated server leaves to the agent.
The refusal comes back as a tool error the agent can read.

## Get the same server from Speakeasy or Kiota

Speakeasy's Standalone MCP documentation generates a TypeScript server from the document with
`speakeasy quickstart --mcp`. Its [`x-speakeasy-mcp`](https://www.speakeasy.com/docs/standalone-mcp/customize-tools)
extension renames a tool, sets `disabled: true` to drop one, or tags it with `scopes` that the
server's `--scope` flag mounts at start. That puts curation in the document rather than in code.
The [maturity matrix](https://www.speakeasy.com/docs/sdks/languages/maturity) grades MCP
TypeScript as Beta. Speakeasy's Gram address redirects to its
[AI Control Plane](https://www.speakeasy.com/docs/ai-control-plane) page, which offers an MCP
Gateway to host and distribute servers.

Kiota 1.39.0 has no server output: its command list, kept in `recorded/kiota-help.txt`, runs from
`generate` to `rpc` with no MCP command, and the table of contents of the Kiota documentation has
no MCP entry. The working
route is the facade: `backend-kiota.mjs` runs the same six tools over the Kiota client, with a
bearer token provider whose one allowed host is the API's. Its models name fields in camel case, so the backend maps
`patientId` back to `patient_id`.

## Reweight for your team

Weights decide the outcome, so try a second set. A team with no time to edit tools puts `upkeep`
at 4 and raises the tool budget to 20:

```bash
node score.mjs api.json weights-upkeep-first.json
```

```text output
api.json: 14 operations, spec quality 0.89, 5 tasks (0.60 need one operation), 4.01 changes a quarter
weights (weights-upkeep-first.json): toolLoad 1, taskFit 1, descriptions 1, schemas 1, upkeep 4; tool budget 20
                         tools  tasks  calls       edits/q  toolLoad     taskFit      descriptions schemas      upkeep       score
openapi-mcp-generator       14    5/5  3 4 1 1 1      0.00  1.00         0.72         0.79         1.00         1.00         94
sdkgen go-mcp, stock         2    2/5  - - - 1 1      0.00  1.00         0.40         0.00         0.00         1.00         68
sdkgen go-mcp, write on      5    5/5  3 4 1 1 1      0.00  1.00         0.72         0.00         0.00         1.00         71
hand-written, fetch          6    5/5  2 2 1 1 1      2.51  1.00         0.80         1.00         1.00         0.16         56
facade over an SDK           6    5/5  2 2 1 1 1      1.00  1.00         0.80         1.00         1.00         0.67         81
highest: openapi-mcp-generator (generated)
```

## Check it worked

The tests rescore both documents under both weights files and refuse a weight that is missing or
not a number. They also run every facade tool over all three backends, and compare each tool's
requests with the operations its entry in `TOOLS` names:

```bash
node --test rubric.test.mjs
```

```text output
1..16
# tests 16
# suites 0
# pass 16
# fail 0
# cancelled 0
# skipped 0
# todo 0
```

## When it goes wrong

The agent cannot book. The stock go-mcp server registers only `list` and `load`. Set
`main: kit: target: 'go-mcp': tool: write: true` in `.sdk/model/project.aontu`, as the model
reference documents, and regenerate.

The agent sends a filter the API does not know. go-mcp's `query` is an open object, so the schema
gives the agent no name for `practitioner_id`. Put a facade tool with named arguments
in front, or score `schemas` higher so the rubric says so.

The score is out of date. Two releases in `changes.json` rename a field or a parameter on
operations the tools call. Add each release to the file when it ships and rerun `score.mjs`.

## When not to do this

Do not score a server you will throw away. A demo for one meeting needs whatever runs first.

Do not decide from the endpoint count. The same 104 operations gave 104 tools, five, or six,
depending on how the server was built.

Do not pick sdkgen's go-mcp target for an agent that writes unless you turn the write tools on,
and expect a free-form query argument either way. Pick Speakeasy when the document is where your
team already curates and a vendor account is acceptable. Pick Kiota when your services already
use its clients and the facade should share them.

Do not take the weights here as yours. They are one team's opinion, written down so that yours can
differ visibly.

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

- [Choose between one tool per operation and one search tool](/howto/choose-tool-granularity-per-operation-or-search)

- [Generate an SDK, a CLI, and an MCP Server from one spec](/howto/sdk-cli-and-mcp-server-from-one-spec)

- [Score SDK generators on your API with a repeatable rubric](/howto/score-sdk-generators-with-a-repeatable-rubric)

## Last verified

Verified 2026-11-22 against Node 22.23.5, `@voxgig/create-sdkgen` 0.31.9 with `@voxgig/sdkgen`
4.44.3, `openapi-mcp-generator` 5.0.1, Kiota 1.39.0, and `@modelcontextprotocol/server` 2.4.0.
Every output block is what the command preceding it printed. The go-mcp servers were built with Go
1.25.0 and listed once, in `record.sh`, on 4.44.3 and again on 4.45.0 with `@voxgig/apidef`
8.33.1; the page reads their recorded tool lists. Speakeasy was not
run, because generation [needs an account](https://www.speakeasy.com/docs/speakeasy-reference/cli/getting-started).

[^1]: The specification does not count tools for anyone. Its
[tools page](https://modelcontextprotocol.io/specification/2026-07-28/server/tools) asks for tool
names between 1 and 128 characters and says that clients MUST consider tool annotations untrusted
unless they come from trusted servers. A `readOnlyHint` is therefore a statement a server makes
about itself, which the client is told to weigh by who made it.

[^2]: The SDK has two published lines. Its
[README](https://github.com/modelcontextprotocol/typescript-sdk) calls v2,
`@modelcontextprotocol/server` and `@modelcontextprotocol/client`, the stable release line, and
says v1, `@modelcontextprotocol/sdk`, receives bug fixes and security updates for at least six
months after the v2 release of 2026-07-27. The servers openapi-mcp-generator 5.0.1 writes depend on
v2 as well.