Your API has 200 operations, and the MCP server generated from it lists 200 tools. Every request to the model carries all of them, 15,818 tokens of definitions before any work starts. Replace them with one search tool and the list shrinks to a few hundred tokens, but each call then waits on discovery calls that a hurried agent skips.
What you get
You will end up with four tool shapes over one 200-operation API, measured on five tasks for calls, tokens, and failures. A check fails when one operation is reachable two ways. This is for you if you publish tools for a large API.
Short answer
Run one fixed task set through each tool shape and count calls, tokens, and failed calls before you choose. Over 200 operations, one tool per endpoint costs 15,818 tokens per request. sdkgen’s go-mcp target lists five verb tools for 1,388. Three meta-tools cost 160 but take more than twice the calls, and fail when the schema call is skipped. Then keep each operation reachable through exactly one tool.
You will need
Node 22 or later, an OpenAPI 3 document for an API with many operations, and an MCP server or a
plan for one. Verified 2026-11-20 against Node 22.23.5. The document here is a Fleet API with
40 resources and five operations each, written by make-api.mjs. Token counts use the o200k
encoding of gpt-tokenizer, a stand-in for any one
model’s tokenizer. The MCP tools specification
defines what a server lists.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Cloudflare Code Mode | Tasks that chain calls, on Cloudflare Workers | An experimental package, plus a sandbox for code the model writes | Tasks are single calls, or model-written code cannot run |
| Hand-written meta-tools | Hundreds of operations and a tight token budget per request | Two discovery calls before each new operation, and a guess when the agent skips them | Agents call a few operations often |
| oapi-codegen | A Go tool server over typed methods that take a context.Context | No tools generated, so every definition and its dispatch is code you keep current | You want the tool list generated with the client |
| openapi-mcp-generator one tool per endpoint | A few dozen operations, or x-mcp filtering keeps the list short | Every listed definition rides on every request: 15,818 tokens here | The API has hundreds of operations |
| sdkgen go-mcp verb tools | An entity-shaped API, with a Go server generated beside the SDK | An open data object with no field schema, and a tool context the calls ignore | The operations are actions rather than entity operations |
| Swagger Codegen | Typed clients in several languages, wrapped as tools by hand | No tools generated, and an untagged document puts all 200 operations on one service | You want the tool list generated with the client |
Voxgig maintains sdkgen. It is one of six options here, not the recommendation.
The shapes trade the cost of a request against the cost of a task. One tool per endpoint is precise per call and pays for 200 definitions every turn. The meta-tools are nearly free to list and spend extra round trips on discovery. Code Mode collapses a task into one call, at the price of running code the model wrote. The two client generators leave the choice, and the dispatch, to you.
Count what each generator made of 200 operations
generate.sh ran each generator once on api.json and kept what the page reads under
generated/. The sdkgen run asks its go-mcp target for the write tools, which are off by
default:
(cd work && npx --yes @voxgig/create-sdkgen@0.31.9 fleet --def ../api.json -t go -t go-mcp)
printf "\n# Generate the write tools too (off by default).\nmain: kit: target: 'go-mcp': tool: write: true\n" \
>> work/fleet-sdk/.sdk/model/project.aontu
(cd work/fleet-sdk/.sdk && npm run generate)
(cd work/fleet-sdk/go-mcp && go build -o ../../fleet-mcp .)
Count the results:
node inventory.mjs
Swagger Codegen 3.0.85, -l go: 200 methods on DefaultApiService
GetVehicle(ctx context.Context, vehicleId string) (Vehicle, *http.Response, error)
oapi-codegen v2.8.2: 280 methods on ClientInterface, 80 of them ...WithBody
GetVehicle(ctx context.Context, vehicleId string, reqEditors ...RequestEditorFn) (*http.Response, error)
openapi-mcp-generator 5.0.1: 200 tools
sdkgen go-mcp: 5 tools, 40 entities in each one's enum
fleet_create, fleet_list, fleet_load, fleet_remove, fleet_update
Both servers answered tools/list in one page.1 The go-mcp target does not emit one tool per entity operation. It emits one tool per verb and
takes the entity as an enum argument, so the list stays at five whether the API has four entities
or forty. Each call goes through one dispatch function:
func runOp(_ context.Context, client *sdk.FleetSDK, op string, entity string, input map[string]any) (*mcp.CallToolResult, any, error) {
ent, err := entityFor(client, entity)
if err != nil {
return toolError(err.Error())
}
var result any
switch op {
case "list":
result, err = ent.List(input, nil)
case "load":
result, err = ent.Load(input, nil)
The context arrives as _ and goes no further, so a client that cancels a tool call does not
cancel the HTTP request behind it. The binary was built and called once, against a stand-in:
cat generated/go-mcp-calls.txt
fleet_load {"entity":"vehicle","query":{"id":"v-17"}}
{ "id": "v-17", "name": "Van 17" }
fleet_list {"entity":"vehicle"}
[ { "id": "v-17", "name": "Van 17" } ]
fleet_create {"entity":"vehicle","data":{"name":"Van 18"}}
{ "id": "v-17", "name": "Van 17" }
fleet_update {"entity":"vehicle","data":{"id":"v-17","status":"parked"}}
{ "id": "v-17", "name": "Van 17" }
fleet_remove {"entity":"vehicle","query":{"id":"v-17"}}
{ "id": "v-17", "name": "Van 17" }
fleet_load {"entity":"vehicle","query":{"vehicleId":"v-17"}}
isError FleetSDK: load: URL path has no value for {id}.
requests the stand-in received:
GET /vehicles/v-17
GET /vehicles
POST /vehicles {"name":"Van 18"}
PATCH /vehicles/v-17 {"id":"v-17","status":"parked"}
DELETE /vehicles/v-17
The record is named by id, whatever the document calls its path parameter, and a wrong key
comes back as a tool error the agent can read.
Run the same five tasks through every shape
tasks.mjs holds five tasks: a read, a create, a delete, a rename, and one that lists faults
and closes the open ones at one site. Each shape gets a scripted policy in place of a model, and
each task runs against a fresh in-memory copy of the API, which then checks the outcome. The
third task, as the step-by-step policies and the code tool see it:
name: 'close every open fault at site cork',
run: async (step) => {
const open = (await step('listFaults')).filter((f) => f.site === 'cork' && f.status === 'open')
for (const f of open) await step('updateFault', { faultId: f.id }, { status: 'closed' })
return open.map((f) => f.id)
},
code: [
"const open = (await api.listFaults()).filter((f) => f.site === 'cork' && f.status === 'open')",
"for (const f of open) await api.updateFault({ faultId: f.id, body: { status: 'closed' } })",
'return open.map((f) => f.id)',
].join('\n'),
The code tool here is a stand-in in the shape the Code Mode documentation describes, a declaration of every operation in one tool’s description. It is not Cloudflare’s code. A task’s requests are its tool calls plus one for the final answer:
node measure.mjs
task set: 5 tasks, o200k tokens
shape tools per request calls failed correct definition tokens result tokens
one tool per endpoint 200 15818 8 0 5/5 205634 405
one tool per verb (go-mcp) 5 1388 8 0 5/5 18044 405
three meta-tools 3 160 20 0 5/5 4000 1375
meta-tools, schema skipped 3 160 22 4 4/5 4320 1333
one code tool 1 4229 5 0 5/5 42290 76
Read the definition column first, because it repeats on every turn of every conversation. Two hundred tools cost about eleven times the five verb tools, for the same eight calls.2 The meta-tools cut the list to 160 tokens and take 20 calls, because each new operation costs a search and a schema read first. The code tool ran each task in one call, and only the code’s return value came back.
The fourth row measures the usual failure of meta-tools. A policy that searches and then invokes with
guessed argument names fails four calls, recovers from each, and still gets one task wrong. The
guessed create passed name and site at the top level, where the tool reads only
requestBody, so the API stored an empty ticket and reported success.
Selection accuracy is not in the table. A scripted policy never picks the wrong tool, so that
column needs a real model behind measure, run on the same five tasks and judged by the same checks.
Wrap a Swagger Codegen or oapi-codegen client in tools
Neither generator writes MCP tools, so with either one the shape is yours to build. The
Swagger Codegen v3 documentation
lists client, server stub and documentation generators but no tool generator. Its Go client put
all 200 operations on one DefaultApiService, because the document tags none of them. Each method takes
a context and returns a typed model, so one tool per method is a short loop of definitions. A
verb or meta-tool shape needs a dispatch table from tool arguments to methods, written by hand.
oapi-codegen generates
Go types and a client, and its README names no tool or MCP output. Its ClientInterface carries
280 methods: one per operation, plus a WithBody variant for each of the 80 operations with a
request body. Every method takes a context.Context and RequestEditorFn callbacks, so a
dispatch layer you write can pass cancellation and credentials through. With both generators,
the per-verb or meta shape from catalogs.mjs is the part you would port to Go.
Check it worked
Eleven tests pin the measurement. They match the 200 operationIds to the 200 tools and check the five verb tools and their 40-entity enums. They pin the order of per-request costs, the meta-tools’ extra calls, and the four failures and empty write when the schema is skipped. One checks that this page’s per-verb dispatch sends the requests the real binary sent.
node --test granularity.test.mjs
1..11
# tests 11
# suites 0
# pass 11
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 301.904722
When it goes wrong
The agent updates a vehicle through one tool and reads it back through another. Someone added
per-endpoint vehicle tools beside the five verb tools, so each vehicle operation is reachable
two ways, with two argument conventions. An approval rule or an audit filter written against one
tool name misses the other. overlap.mjs lists every operation more than one tool reaches:
node overlap.mjs
go-mcp tools alone: 5 tools, 0 operations reachable two ways
go-mcp tools plus five vehicle tools: 10 tools, 5 operations reachable two ways
createVehicle fleet_create, createVehicle
listVehicles fleet_list, listVehicles
getVehicle fleet_load, getVehicle
deleteVehicle fleet_remove, deleteVehicle
updateVehicle fleet_update, updateVehicle
fleet_load {entity, query.id} and getVehicle {vehicleId} both sent: GET /vehicles/v-17, GET /vehicles/v-17
In CI, assert that overlaps() returns nothing for the catalog you ship, as the test does, and
pick one shape per server.
The verb tools write a field the API does not have. fleet_create takes data as an open object,
so the schema cannot tell an agent the record’s field names. Put the field list in the
description, or keep per-endpoint tools for the few writes where shape matters.
fleet_load answers URL path has no value for {id}. The agent named the record with the
document’s path parameter, vehicleId, but the verb tools read id from query. Send
query: { id }, the form the tool’s own description gives as its example.
When not to do this
Do not mix tool shapes in one server. An operation reachable through two tools splits every rule keyed on a tool name, and the measurement on this page cannot see which route an agent will take.
Do not pick sdkgen’s go-mcp verb tools for an API whose operations are actions. Five verbs over an entity enum describe a CRUD API well, but an endpoint such as a refund or a dispatch has no verb to sit under. Its tools also drop the call’s context, so cancellation stops at the server.
Do not ship meta-tools to agents that call the same handful of operations all day. They pay two discovery calls per operation per conversation, which a short list of named tools avoids.
Choose oapi-codegen for a Go tool server where each tool must honor cancellation and pass per-request credentials, since every method takes a context and request editors. Choose Swagger Codegen when the tools wrap clients in several languages and each needs a typed method per operation.
Related how-tos
Last verified
Verified 2026-11-20 against Node 22.23.5, Go 1.25.0, @voxgig/create-sdkgen 0.31.9,
@voxgig/sdkgen 4.44.3, openapi-mcp-generator 5.0.1, Swagger Codegen 3.0.85, oapi-codegen v2.8.2
and gpt-tokenizer 4.1.2. Every output block is what the command preceding it printed. Each
generator ran once in generate.sh, and its output is committed under generated/. The go-mcp
binary and the openapi-mcp-generator server were started to list their tools and are not
re-run on each build. Cloudflare Code Mode was not run; its shape comes from its documentation.
Footnotes
-
The MCP pagination rules let a server split a long
tools/listinto pages, with the page size set by the server and a cursor to ask for the next one. Neither server here used them. The per-endpoint server sent all 200 definitions in its first and only page, which is the whole tool list a client will forward. ↩︎ Back to text -
Cloudflare’s post on Code Mode for MCP starts from a larger catalog. Its summary says the Cloudflare API has over 2,500 endpoints, that one MCP tool each would consume over two million tokens, and that two tools and roughly 1,000 tokens replaced them. The body of the same post gives a lower figure for that server, 1.17 million tokens measured with
tiktoken, which comes to about 470 an endpoint. The Fleet document here averages 79 a tool, with four fields in each schema. ↩︎ Back to text