OpenAPI to MCP Converter

Convert an OpenAPI 3.0 or 3.1 spec into MCP tools and a TypeScript MCP server that calls the API with fetch. Pick operations, resolve $refs, see warnings.

The interactive tool loads here when JavaScript runs.

About this tool

What is the OpenAPI to MCP Converter?

Paste an OpenAPI 3.0 or 3.1 document in JSON or YAML, or open the file, and every operation becomes a candidate MCP tool. Its name comes from the operationId (or the method and path), its description from the summary and description, and its inputSchema from the path, query and header parameters plus the JSON request body, with local $refs resolved.

Tick the operations you want and the converter writes a TypeScript MCP server on the official SDK that calls the API with fetch, reading the base URL and credentials from environment variables, plus the tool list as JSON, package.json, tsconfig.json, a README and an example client config. Warnings point out what it could not map. The spec is parsed in your browser and never uploaded.

  • OpenAPI 3.0 and 3.1 in JSON or YAML
  • Local $ref resolution with cycle protection
  • Path, query and header parameters plus JSON request bodies
  • Tool names from operationId or method and path, sanitised and de-duplicated
  • Operation picker with filter, and warnings for unsupported features and long tool lists
  • TypeScript MCP server on the official SDK with fetch, env-based base URL and auth
  • tools.json, .env.example, README and zip download
Read the guide: How to Build an MCP Server in TypeScript or Python

Updated

How to use the OpenAPI to MCP Converter

  1. Paste the spec, open a .json or .yaml file, or load the pet store sample.
  2. Check the API summary: OpenAPI version, base URL and detected authentication.
  3. Tick the operations to expose; filter by path, tag or tool name.
  4. Read the warnings, set a server name, then download the zip or copy the files.
  5. Run npm install and npm run build, test with MCP Inspector using -e to pass API_BASE_URL and the credential, then add the server to your client.

Worked examples

Pet store sample

Input

GET /pets with a $ref limit parameter, POST /pets with a $ref NewPet body, a multipart photo upload

Output

Tools list_pets, create_pet, get_pet, delete_pet; upload flagged and left unticked

The limit parameter keeps its minimum, maximum and default; NewPet loses its readOnly id and its nullable birthday becomes ["string", "null"].

Bearer auth

Input

securitySchemes bearerAuth: type http, scheme bearer

Output

The server sends Authorization: Bearer $API_TOKEN on every call

API keys in a header or query and HTTP Basic are handled the same way with API_KEY or API_USERNAME and API_PASSWORD.

Background and insight

OpenAPI already describes most of what an MCP tool needs: a name, a description and a JSON Schema for the inputs. The mapping here puts path, query and header parameters at the top level of the inputSchema (path parameters are always required), puts a JSON request body under a "body" property, converts OpenAPI 3.0's nullable: true into a JSON Schema type array, drops readOnly properties from request bodies and removes OpenAPI-only keywords such as discriminator and xml. Accept, Content-Type and Authorization header parameters are skipped, as the OpenAPI specification says they are ignored.

Some things do not translate. File uploads (multipart/form-data), form posts and other non-JSON bodies are reported and skipped, as are cookie parameters and callbacks. oneOf and anyOf unions are kept but flagged, because models fill complex unions less reliably. Recursive $refs are expanded once, and external $refs to other files are not fetched. Swagger 2.0 documents need converting to OpenAPI 3 first.

Tool count matters. OpenAI's function calling guide suggests keeping fewer than 20 functions available at once, and Google's Gemini docs suggest 10 to 20. A full API often has hundreds of operations, so the converter warns above 40 and lets you filter and pick the ones an agent actually needs.

Common use cases

  • Giving agents an existing API

    Let Claude, Cursor or Codex call your REST API without hand-writing each tool.

  • Internal platforms

    Expose a few safe read operations from an internal service to a team assistant.

  • API product teams

    Ship an MCP server alongside your public API from the spec you already maintain.

  • Spec review

    See how clear your summaries and parameter descriptions are when a model is the reader.

Tips and limitations

  • Start with read-only GET operations and let your client ask for confirmation before any POST, PUT, PATCH or DELETE.
  • Rewrite thin summaries: "List pets" tells a model less than "List pets, newest first; filter by species".
  • Trim large responses in the generated callApi function to the fields a model needs; the default cut-off is 20,000 characters.
  • If your API needs OAuth, get and refresh the token outside the server and pass it as API_TOKEN.
  • Group dozens of similar endpoints into a few task-level tools by hand once you know which calls agents make.

Frequently asked questions

Can I convert a Swagger 2.0 file?

Not directly. Convert it to OpenAPI 3 first, for example with the Swagger Editor or a converter library, then paste the result.

How are tool names chosen?

From the operationId, converted to snake_case and limited to letters, digits, underscores and hyphens up to 64 characters. Without an operationId the name is the method and path, such as get_pets_by_pet_id.

How many operations should I expose as tools?

As few as the agent needs. Model accuracy drops as the tool list grows; OpenAI suggests fewer than 20 at a time, and the converter warns above 40.

How does the generated server authenticate?

It reads credentials from environment variables based on the spec's security scheme: API_TOKEN for bearer or OAuth tokens, API_KEY for API keys, API_USERNAME and API_PASSWORD for Basic. Your MCP client passes them in its env block.

Are file uploads supported?

No. multipart/form-data and other non-JSON bodies are listed as warnings and the tool sends no body. Upload endpoints need hand-written code.

Is my OpenAPI spec uploaded?

No. It is parsed with a YAML library in your browser and the code is generated there.

Is there an in-depth guide to the OpenAPI to MCP Converter?

Yes. “How to Build an MCP Server in TypeScript or Python” covers the background, how it works, common pitfalls and worked examples. Read the full guide.

Related Tools You May Like

Free, in-browser tools that pair well with this one.