Every OpenAPI operation needs an operationId — it becomes the MCP tool name.
MCP build guide
Build an MCP server from your OpenAPI spec.
Three paths to a working MCP server in 2026: write it by hand using the MCP SDK, generate it from OpenAPI with a code generator, or use a managed pipeline that emits the server alongside your SDKs. Here is the practical version of each.
Unlimited previews. No credit card required.
01Details
Before you start: the spec hygiene that matters
Request bodies should be defined as components/schemas references, not inlined. The MCP tool input schema is the request schema.
Every operation needs at least one example. MCP clients use these to suggest sample inputs to the user.
Security schemes defined and applied — the MCP server needs to know which header to forward.
02Details
Path 1: Hand-rolled with @modelcontextprotocol/sdk
Install: npm install @modelcontextprotocol/sdk zod.
Define each tool with server.tool(name, description, inputSchema, handler). The handler makes the actual HTTP call to your API.
Stdio transport for local: new StdioServerTransport() + server.connect(transport).
Best when you have 5-10 endpoints and want full control of the tool surface. Doesn't scale past ~20 endpoints — too many handlers to maintain.
03Outputs
Path 2: Generate from OpenAPI locally
Use a converter like openapi-mcp-generator to emit one tool per operation from an OpenAPI 3.x spec.
Output is a standalone Node or Python package with one file per resource group.
Trade-off: you own the generated code; spec changes mean re-running the generator and resolving any output drift.
Good for teams that want full code ownership and are willing to maintain the generator pinning.
04Details
Path 3: Sourced — MCP + SDKs + docs from one OpenAPI source
TypeScript and Python SDKs ship today, and the standalone MCP generator emits a downloadable server bundle from the same OpenAPI source.
Preview output has one starter tool per OpenAPI operation, with path/query/body fields extracted for review before deeper schema hardening.
Stdio transport ships first; hosted Streamable HTTP remains a release-pipeline follow-up.
Compatibility report runs on every spec change so SDK breakage is visible before publish; MCP tool drift can be reviewed from the generated tool list before any package release.
05Details
Installing the resulting MCP server (any path)
MCP clients converge on a { mcpServers: { your-api: { command, args, env } } } config block.
Drop into ~/.cursor/mcp.json, Claude Desktop's claude_desktop_config.json, ~/.gemini/config/mcp_config.json, or use codex mcp add / cline mcp install.
If publishing to npm: npx -y @your-co/mcp is the canonical install command.
If hosted: { url: "https://mcp.your-co.com", headers: { Authorization: "Bearer ..." } }.
06Details
Publish to the MCP registry
The official registry at https://registry.modelcontextprotocol.io is the canonical discovery surface for MCP-aware clients.
Submit via the mcp-publisher CLI (brew install mcp-publisher → mcp-publisher login github → mcp-publisher publish).
Namespace must match GitHub org: io.github.your-org/your-api. Add a matching mcpName field to the npm package.json for verification.
Also list on mcp.so and smithery.ai for additional discovery.