Sourced*

How-to

Generate an MCP server from OpenAPI

· 6 min read · Sourced

  • openapi
  • mcp
  • codegen
  • agents

To generate an MCP server from OpenAPI, you map each spec operation to an MCP tool, convert its request schema into the tool's argument schema, wire securitySchemes to environment-variable auth, and point the HTTP layer at servers[0].url — either by hand with the official MCP SDK or with a generator like Sourced's OpenAPI-to-MCP generator. If you have an OpenAPI 3.x spec, you already have most of what an MCP server needs; the translation is mostly mechanical.

That does not mean every generated tool is ready for production. This post is the short version of what's possible today, what works cleanly, and what still needs human review. (New to MCP? Start with the MCP overview hub for what a server is, how hosts connect, and the build guides per language.)

Fast path

  1. Paste or upload the OpenAPI spec.
  2. Review tool names and descriptions before installing anything.
  3. Mark destructive operations such as delete, refund, revoke, send, or publish.
  4. Configure auth through environment variables or the host's secret store.
  5. Test one read-only tool first.
  6. Install the MCP server in ChatGPT API, Grok, Claude, Hermes, OpenClaw, Cursor, VS Code, Cline, or Continue only after the surface looks safe.

What translates cleanly

1. Operations → tools

Each OpenAPI operation becomes one MCP tool. The mapping:

  • operationId → tool name. Some generators preserve casing exactly; others normalize names. Sourced preserves the generated operation identifier so the tool name stays stable across exports.
  • summary → tool description (the agent reads this when deciding what to call).
  • description → extended tool documentation.
  • tags → tool grouping (some MCP servers expose tags as namespaces).

A clean operationId and summary produce a clean tool surface. The OpenAPI best practices post covers what "clean" looks like.

2. Request schemas → argument schemas

The OpenAPI request body and parameters become the MCP tool's argument schema. JSON Schema 2020-12 (OpenAPI 3.1) translates more directly than OpenAPI 3.0, which may need a small nullable: true → type: [..., "null"] shim.

Required parameters stay required in the generated input schema. Defaults, enums, and examples should be reviewed in the generated output because support varies by generator and host.

3. Auth schemes → MCP auth

OpenAPI securitySchemes declare what credentials the API expects. Sourced's generated starter reads upstream API credentials from environment variables and keeps hosted OAuth-style connectors blocked until consent, callbacks, token storage, refresh behavior, and host review are designed:

  • apiKey in header or query → <NAME>_API_KEY env var.
  • http bearer → <NAME>_API_KEY env var, sent as Authorization: Bearer ....
  • basic → <NAME>_BASIC_AUTH env var.
  • oauth2 or OpenID Connect → <NAME>_ACCESS_TOKEN for local testing only; hosted connector setup needs a real OAuth flow.

4. Base URLs → HTTP layer

servers[0].url becomes the base URL the MCP server proxies to. If the OpenAPI spec has multiple environments (sandbox + production), the MCP server should expose them as separate connections or accept a base_url env var.

What needs human input

1. Tool granularity

OpenAPI operations are typically fine-grained (one per HTTP verb per resource). MCP tools work better when they're task-shaped (book_appointment rather than create_event + attach_attendees + send_invite).

A good OpenAPI-to-MCP generator will emit one tool per operation by default and let you override with custom tool definitions for higher-level workflows. You write the override; the generator handles the boilerplate.

The best MCP surfaces are usually smaller than the full API. Start with read-only and high-confidence operations, then add write operations after confirmation behavior is clear.

2. Tool descriptions tuned for an agent reader

OpenAPI summary and description are written for human developers reading docs. MCP tool descriptions are read by an AI agent deciding whether to call. The wording differs.

A human-targeted summary: "Send a message to a phone number."

An agent-targeted description: "Send an SMS message to a phone number. The agent should use this when the user explicitly asks to text someone. Do NOT use this for emails (see send_email). Do NOT use this for group messages (see send_group_message). Always confirm the phone number with the user before calling."

The agent-targeted version reduces miscalls. Most generators won't write these for you; plan to author them by hand for the tools that matter most.

3. Destructive vs read-only tagging

OpenAPI has no concept of "this operation is destructive." MCP servers benefit from marking destructive tools so the client can prompt for confirmation. Add a custom OpenAPI extension such as x-mcp-destructive: true, map it into MCP tool annotations, and still require human confirmation for risky operations.

4. Rate limits and timeouts

OpenAPI doesn't model per-operation rate limits. MCP servers should — see the MCP security post. You add these as generator configuration, not from the spec.

Tools that ship OpenAPI-to-MCP today

Stainless's MCP target

Stainless ships MCP server generation alongside SDK and docs targets. It is worth evaluating if you are already on Stainless and want MCP tied to the same project config.

openapi-mcp-generator (open-source)

A community project that walks an OpenAPI 3.x spec and emits an MCP server skeleton. Less polished than Stainless's target but free and forkable.

Hand-written using @modelcontextprotocol/sdk

For small APIs (<20 operations) or for higher-level tool surfaces, hand-writing is often cleaner than codegen. The SDK gives you typed server.tool(name, description, schema, handler) registrations; you wire each to your existing API.

Sourced

Sourced ships a browser-based OpenAPI-to-MCP generator today. Paste an OpenAPI spec, review the generated tool surface, and download an Agent Interface Pack with a TypeScript MCP server, safety report, host connector files, tests, and install snippets for ChatGPT API, Grok, Claude, Hermes, OpenClaw, Cursor, VS Code, Cline, and Continue.

Sourced's current starter turns OpenAPI paths operations into MCP tools, classifies read/write/destructive operations, and keeps remote connector output blocked until a public HTTPS MCP endpoint and required endpoint auth are verified. Nested bodies, OAuth2 flows, top-level webhooks, and official MCP tool annotations should still be reviewed before production hardening.

Other API-docs platforms are also adding MCP surfaces. The important comparison is not "does it say MCP?" It is whether the generated tools are safe for agents: stable names, narrow descriptions, explicit auth, destructive-action markers, and review before installation.

The same spec-quality work that improves SDKs also improves the MCP server: clean operation names, good summaries, proper schemas, descriptive auth schemes, and explicit destructive-action notes.

Migration shape, when you switch generators

If you're moving from one OpenAPI-to-MCP generator to another, the SDK compatibility report pattern applies:

  • List old and new tool names.
  • Diff argument schemas (additions OK; removals or type narrowings are breakage).
  • Diff auth requirements per tool.
  • Diff destructive-action handling.

A clean cutover keeps the MCP client config stable on the customer side.

What to do this week

  • Audit your OpenAPI spec against the best-practices post. Clean spec → clean MCP server.
  • If you ship a developer product and don't have an MCP server, evaluate Stainless's target (if you're already a customer) or hand-write a small one using the official SDK.
  • If you ship MCP today, walk the security checklist — confirmation flows, rate limits, structured errors.

The MCP standard is young but the OpenAPI side is mature. Most of the work to ship an MCP server is work you've already done on your REST API.

Try the OpenAPI-to-MCP generator or start free to generate a full docs and SDK preview first.