How-to › Expose your API to agents

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.

Audience
API producer
Level
beginner
Topic
Build an MCP server
Verified

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
Hand-written server on the official TypeScript MCP SDKA few tools shaped like the agent’s tasks, over a client you also ownA handler, schema, and description per tool, edited by hand on every change to the APIThe document changes every week and nobody owns the tools
Kiota client behind a hand-written facadeYou already ship Kiota clients and want the facade in a language Kiota targetsKiota writes a client, not a server, so every tool is yours to writeYou want any tool generated for you
openapi-mcp-generatorA TypeScript server with one typed tool per operation, regenerated in secondsOne tool per endpoint, so the agent’s choice grows with the documentThe tasks span several operations, or the document has a hundred
sdkgen go-mcp targetYou generate the SDK with sdkgen and want a server from the same modelRead-only until configured, a free-form query argument, and descriptions from a templateThe agent writes, or needs the parameters named in the schema
Speakeasy Standalone MCPYou use Speakeasy and want curation in the document with x-speakeasy-mcpAn account, a target graded Beta, and extensions written into the documentYou 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.

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

  1. 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 readOnlyHint is therefore a statement a server makes about itself, which the client is told to weigh by who made it. ↩︎ Back to text

  2. The SDK has two published lines. Its README 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. ↩︎ 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.