Free tool

OpenAPI to MCP Server in TypeScript

You already have an OpenAPI spec. Here is how it becomes a working MCP server in TypeScript, and which parts a converter cannot do for you.

Official SDK modelcontextprotocol/typescript-sdk
Install
npm install @modelcontextprotocol/sdk zod
A working MCP tool in TypeScript 
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

server.tool(
  "get_order",
  "Look up one order by its id and return its current status.",
  { orderId: z.string().describe("The order id to look up") },
  async ({ orderId }) => ({ content: [{ type: "text", text: await fetchOrder(orderId) }] })
);
Test what you built Generate tools from an OpenAPI spec

Generated, running, and still invisible.

Converting a spec gets you a server. It does not get you anyone who wants to use it. MCP Showcase turns the same endpoint into a live playground with readable documentation for every tool.

Start for Free Explore the MCP server directory

How it works

link
Convert the spec

The OpenAPI converter turns each operation into an MCP tool definition, in your browser, without uploading your spec.

play_circle
Wire it up in TypeScript

Take the generated tool definitions and implement them against your API using the TypeScript SDK, in the shape shown above.

checklist
Cut the list down

A converted spec gives you one tool per operation, which is almost always far too many. Keep the ones an agent needs.

From spec to TypeScript

The mechanical half is genuinely mechanical: each OpenAPI operation becomes one MCP tool, its summary becomes the description, and its path, query and body parameters flatten into a single input schema. The OpenAPI converter does that part in your browser, without uploading your spec.

What remains is TypeScript-shaped: implementing those tools against your API with modelcontextprotocol/typescript-sdk (npm install @modelcontextprotocol/sdk zod), in the form shown above.

Your Zod schema is the contract the model sees

The TypeScript SDK builds the JSON Schema from Zod, so `.describe()` on each field is not documentation for your colleagues -- it is what tells the model what to put there. Schemas written without it validate perfectly and leave the agent guessing at every parameter.

What no converter can do for you

  • Authentication. Generated code calls your API with no credentials. Wiring in the header, token or OAuth flow is yours.
  • Rewriting the descriptions. An OpenAPI summary is written for a developer reading documentation. An MCP tool description is read by a model deciding what to call. Those are different jobs, and summaries usually need rewriting once converted.
  • Choosing what to expose. A converter will hand you one tool per operation. For most APIs that is an order of magnitude too many.
  • Expanding $ref bodies. Resolving them needs your components section, so they come across as a generic object.

Why the tool count matters so much

Tool definitions are sent to the model on every request, not once per session. Eighty operations means eighty descriptions and eighty schemas in the context window of every turn — paid for continuously, and measurably worse at selection than a short list. The token calculator shows what a given list costs; the schema linter shows whether the descriptions survived conversion in a usable state.

Related tools and guides

Generated is not the same as usable

A converted server proves the mapping worked. It tells a prospective customer nothing — they cannot read TypeScript and will not configure a client to find out. MCP Showcase turns the same endpoint into a live playground with per-tool documentation anyone can try in a browser.

Frequently asked questions

The mapping is mechanical: each operation becomes a tool, its summary becomes the description, and its parameters become one flat input schema. What is not mechanical is authentication, error handling and deciding which operations belong in the tool list at all.

Authentication, which you add yourself. Request bodies behind a $ref, which need your components section to expand. And judgement — a converter will happily give you eighty tools, which is worse than eight.

Because tool definitions are sent to the model on every request. Eighty operations means eighty descriptions and eighty schemas in the context of every turn, paid for continuously, while making the model measurably worse at choosing between them.

Yes, and that is worth knowing before you convert. OpenAPI summaries are written for developers reading documentation; MCP tool descriptions are read by a model deciding what to call. They are not the same job, and summaries usually need rewriting afterwards.

Deploy it and run the URL through the MCP Inspector to confirm the handshake and the tool list, then through the schema linter to see whether the descriptions carried over well enough for a model to choose correctly.

More free MCP tools

MCP Inspector Online

Paste an MCP server URL and see every tool, resource and prompt it exposes, with full schemas and the raw request log. Nothing to install.
MCP Server Tester

Check that your MCP server actually works. Paste the URL and get a pass/fail report on the connection, the handshake, the transport and the tools it advertises.
MCP Security Scanner

Before you point an agent at an MCP server, see what it is asking for. Graded A–F on transport, authentication, tool-poisoning markers and dangerous parameters.
MCP Token Calculator

Tool definitions are sent on every request, not once. Paste your MCP server URL to see how many tokens that is, which tools are the heaviest, and what it costs.
See all free tools