Your API has fourteen endpoints, so a generator gives the agent fourteen tools. Booking an appointment takes three of them in order, and the agent picks each one out of the fourteen. The API grows to 104 endpoints, the generated server follows it, and the booking now starts with 104 tools on the table.
What you get
You will end up with a scored choice between generating, hand writing, and a facade over a generated client, from inputs and weights you commit and a script you rerun. This is for you if you own the API and must decide before you build.
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. 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 | 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 | 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 | 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 | 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 | 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:
{
"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:
node score.mjs api.json
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:
node score.mjs api-large.json
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:
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:
node demo.mjs
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
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 grades MCP
TypeScript as Beta. Speakeasy’s Gram address redirects to its
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:
node score.mjs api.json weights-upkeep-first.json
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:
node --test rubric.test.mjs
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
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.
Footnotes
-
The specification does not count tools for anyone. Its tools page 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
readOnlyHintis therefore a statement a server makes about itself, which the client is told to weigh by who made it. ↩︎ Back to text -
The SDK has two published lines. Its README calls v2,
@modelcontextprotocol/serverand@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. ↩︎ Back to text