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.
Completely free for 30 days. 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: Bloom — MCP + SDKs + docs in one pipeline (preview)
TypeScript and Python SDKs ship today. MCP-server emission is in preview alongside the same pipeline.
Preview output is an npm-shaped package (@your-co/mcp) with one tool per OpenAPI operation, sharing schemas with the SDKs.
Stdio transport first; Streamable HTTP variant (--port N) is on the near-term roadmap.
Compatibility report runs on every spec change so SDK breakage is visible before publish; MCP-tool drift will join the same report once GA.
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.