Implementation guide
OpenAPI to MCP in TypeScript
An OpenAPI operation already contains most of the information an MCP client needs to discover a tool: a stable name, a description, a JSON-shaped input schema, and enough HTTP metadata to execute the request.
Generate your MCP serverMap operations to tool definitions
Use operationId as the tool name when it is present. Convert path, query, and header parameters into JSON Schema properties. Add the application/json request body under a body property so transport metadata never leaks into the model-facing interface.
server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: operations.map(({ name, description, inputSchema }) => ({
name, description, inputSchema,
})),
}));Keep execution separate from discovery
A generated operation registry should contain declarative metadata only. The API client can then apply path replacements, query serialization, headers, authentication, timeouts, and response limits consistently for every tool.
Choose the right transport
Use stdio for local clients such as Cursor and Claude Desktop. Use a secured HTTPS Streamable HTTP endpoint for remote clients. Do not expose a write-capable server publicly without MCP-side authentication and authorization.
Frequently asked questions
Do MCP tools require Zod?
No. The protocol exposes JSON Schema. Zod is convenient with high-level SDK helpers, while the lower-level server API can return JSON Schema directly.
Should every endpoint become a tool?
Usually not. Prefer a small, intentional tool set with clear descriptions and safe authorization boundaries.