Skip to content
openapi-mcp

Changelog

Release history for openapi-mcp-generator, summarized from the repository CHANGELOG.

By Updated

A summary of notable releases. The full history lives in CHANGELOG.md and on GitHub Releases.

5.0.0 (2026-10-24)#

A major release: MCP 2026-07-28, JSON Schema validation without eval, tool annotations, structured output, per-operation servers, a browser playground and Node.js 22+.

Breaking

  • MCP 2026-07-28 via the TypeScript SDK v2. Generated servers depend on @modelcontextprotocol/server and serve both MCP 2026-07-28 clients and 2025-era clients that start with initialize. streamable-http and Worker servers are stateless (GET and DELETE on /mcp answer 405); web (SSE) stays on the 2025-era protocol.
  • Node.js 22 or later. The generator needs Node.js 22.19+.
  • JSON Schema validation. Arguments are validated with @cfworker/json-schema (JSON Schema 2020-12, no eval) on Node and Workers. Defaults are no longer injected and unknown body properties are no longer stripped. Integers stay integers, readOnly properties are left out of inputs, and example becomes examples.
  • Unknown tools answer JSON-RPC -32602 instead of an isError result.
  • Missing upstream credentials fail closed with an error naming what to set. MCP_ALLOW_MISSING_CREDENTIALS=true restores the old behavior; {} keeps anonymous access.
  • Swagger 2.0 is refused with a conversion hint, in the CLI and the programmatic API.
  • Leaner projects. .env is loaded with process.loadEnvFile(); zod, json-schema-to-zod, dotenv and uuid are gone, and ESLint and Jest configs are no longer generated.

Added

  • Tool annotations derived from the HTTP method, overridable with x-mcp-annotations, and titles from x-mcp-title or the summary.
  • JSON object responses are also returned as structuredContent. --output-schema declares and enforces each tool's outputSchema.
  • Per-operation and per-path servers.
  • The spec's info.description is sent as server instructions.
  • --include-tags, --exclude-tags, --include-operations and --exclude-operations, plus matching programmatic options.
  • A browser playground served at / by web, streamable-http and Worker servers. MCP_PLAYGROUND=off turns it off.
  • Generated Workers answer CORS on /mcp, including on 401 responses.

Fixed

  • The browser test page of web and streamable-http servers was never served, and it could not talk MCP. The playground replaces it.
  • OpenAPI 3.0 boolean exclusiveMinimum and exclusiveMaximum are converted to numeric bounds, including in nested schemas.

Upgrading from 4.x#

  1. Commit or back up your generated project. Regenerating with --force overwrites generated files, including your edits.
  2. Regenerate with the same flags: npx openapi-mcp-generator@5 --input ./openapi.json --output ./my-mcp --force.
  3. Use Node.js 22 or later (22.19+ for the generator), then run npm install. Remove leftover .eslintrc.json and jest.config.js if you did not add those tools yourself.
  4. Customized code must import from @modelcontextprotocol/server (stdio helpers from @modelcontextprotocol/server/stdio) instead of @modelcontextprotocol/sdk.
  5. streamable-http and Worker servers no longer use sessions; MCP_SESSION_IDLE_TIMEOUT is ignored. Tool calls over POST work as before.
  6. Configure the credentials your operations require, or set MCP_ALLOW_MISSING_CREDENTIALS=true.
  7. Clients that treated an unknown tool as an isError result must handle JSON-RPC -32602.
  8. Check callers that relied on fractional integers, readOnly inputs, injected defaults or stripped body properties.
  9. Convert Swagger 2.0 specs first: npx swagger2openapi swagger.json -o openapi.json.
  10. Unchanged: credential variables, Worker secret names, --inbound-auth, --header-passthrough and MCP_ALLOWED_ORIGINS.
  11. Not ready to move? Pin the previous major: npx openapi-mcp-generator@4.

4.2.0 (2026-10-24)#

Added

  • --inbound-auth bearer for web, streamable-http and cloudflare-worker. Tokens come from MCP_AUTH_TOKEN or comma-separated MCP_AUTH_TOKENS, are compared in constant time and never written to files. With no token configured the endpoint fails closed with 503; /health stays public.
  • --header-passthrough works on the Worker target.
  • A generation-time warning when an HTTP target would hold upstream credentials without inbound auth.
  • OpenID Connect schemes on the Worker read <SCHEME>_TOKEN.
  • SECURITY.md with a private reporting channel.

Fixed

  • Security requirements follow OpenAPI semantics: requirement objects are alternatives, and every scheme inside one is applied. OAuth2 tokens use the operation's scopes.
  • web and streamable-http return 403 to browser requests from origins that are not loopback or listed in MCP_ALLOWED_ORIGINS.
  • streamable-http no longer crashes on a client's second request, and concurrent clients work with current SDK releases.
  • Generated Worker projects install and type-check cleanly again.

Upgrading from 4.1: regenerate and run npm install. Browser clients of Node HTTP servers may need their origin added to MCP_ALLOWED_ORIGINS.

4.1.0 (2026-06-14)#

  • New cloudflare-worker transport. Generates a deployable Workers project serving Streamable HTTP at /mcp, with only @modelcontextprotocol/sdk and zod as dependencies. Deploy with npx wrangler deploy.
  • Warns at generation time when the spec's servers URL is relative, and fails fast when no base URL can be resolved.
  • Generated Worker projects include a .gitignore covering .dev.vars, node_modules/, .wrangler/ and dist/.
  • HTTP auth scheme names are matched case-insensitively.
  • The generated README documents that the Worker is public by default and how to add authentication.

4.0.1 (2026-06-14)#

  • Fixed: loading a spec from an http(s) URL failed after the 4.0.0 SSRF guard. The guard now applies only to external $refs inside the spec.
  • Fixed: relative $refs in multi-file specs now resolve against the spec's directory.

4.0.0 (2026-06-13)#

Security

  • Escapes ${ sequences from spec descriptions to prevent template-literal injection in generated code.
  • Rejects external http(s) $refs by default (--allow-external-refs to opt in).

Added

  • --max-tool-name-length (default 64) with word abbreviation and hash fallback.
  • --header-passthrough, --insecure, --generate-lib, --custom-auth and --oauth-creds-in-body.
  • OpenAPI tags and deprecated status surfaced on tools.
  • Port resolution from --port, then PORT, then 3000.

Fixed

  • OAuth2 environment variables now resolve from the runtime scheme name.
  • HTTP basic auth works with an empty password.
  • Array query parameters are serialized as comma-separated values.

3.3.0 (2026-03-03)#

  • API_BASE_URL environment variable overrides the spec's servers value.
  • Path-level parameters are merged correctly with operation-level parameters.

3.2.0 (2025-08-24)#

  • Endpoint filtering with the x-mcp extension and the --default-include option.

3.1.0 (2025-05-18)#

  • Programmatic API: getToolsFromOpenApi.

3.0.0 (2025-04-26)#

  • Streamable HTTP transport.

Earlier#

See the full changelog for 1.0.0 through 3.1.4.

PreviousFAQ