openapi-mcp-server: letting an agent read an OpenAPI spec without reading the spec

The problem: a specification an agent will not read

An OpenAPI specification is a large, deeply nested document that describes an API in a form written for machines. The paths, the parameters, the schemas, the security definitions. An agent that has to work with an API is often handed the specification and asked to call it, and the result is that the agent either reads a few thousand lines of YAML to find one endpoint, or guesses.

openapi-mcp-server is a Model Context Protocol server for Claude and Cursor that enables searching and exploring OpenAPI specifications through oapis.org. The MCP server is the transport: it exposes tools that a client calls, and the client asks questions in the shape of a search rather than in the shape of a document.

The audience is a developer with a large or unfamiliar API who wants an agent to work against it accurately. The homepage is openapisearch.com, and the related projects are linked from the project description: OpenAPISearch, which is the search index behind it, and OAPIS, the specification repository. So the design is not a general purpose OpenAPI parser that you point at a local file. It is a client for a registry, and the registry is the point.

The features list is short and honest about its scope: an overview of any OpenAPI specification, details about specific API operations, support for both JSON and YAML formats, and testing against Claude Desktop and Cursor.

The three step path from a name to a usable endpoint

The mechanism is described as a three step process, and the sequence explains the whole design.

First, the server works out which OpenAPI identifier you need. Second, it requests a summary of that specification in simple language. Third, it determines which endpoints you need and works out how exactly they work, again in simple language.

The order matters. An agent talking to a raw specification has to parse it; an agent talking to a summarised specification gets the shape of the API in a form it can reason about, and then drills into the operations it has decided are relevant. The summary is the compression step that makes the rest practical, and it is the reason the server exists rather than a simple file reader.

The simple language is the product decision, and it is also the trade. A model reading YAML can be precise about a parameter type and a model reading a summary is precise about intent. For the common case, where the agent needs to know which operation to call and what it roughly does, the summary wins. For the unusual case, where the agent needs the exact schema of a nested object, the summary is a step backwards, and the client has to fall back to the underlying specification.

The listing of capabilities in the project description maps onto this flow. Getting an overview is the first step, retrieving details about specific operations is the third, and the JSON and YAML support is about how the specification is fetched and parsed rather than about the summary.

Running it: a hosted URL, or the worker on your own machine

The installation path depends on the client. The project documentation points at an install badge for the OpenAPI MCP Server, and for other clients it gives the MCP URL directly:

https://openapi-mcp.openapisearch.com/mcp

That is the whole installation for a client that can be pointed at a remote MCP server. There is no package to add and no API key to obtain, which is a genuine advantage for a first evaluation: the client asks the server, the server resolves the identifier against oapis.org, and the summary comes back.

For local work, the documentation gives a two step procedure. You start the server with the Cloudflare Workers development command:

wrangler dev

and then attach the MCP inspector to it:

npx @modelcontextprotocol/inspector

The inspector is the debugging tool from the Model Context Protocol ecosystem, and running it against the local worker is how you see the tool calls, the arguments and the responses without going through a chat client.

The presence of wrangler in the workflow is the architectural hint. The server is a Cloudflare Worker, a single TypeScript entry point called worker.ts, described by a wrangler.json. There is no container, no server framework and no database. That is why the repository is a handful of files, and it is also why the local run and the hosted run are the same code.

What the worker does with the specification

The dependency list is short and tells you what the server actually does with the document it fetches. The package.json declares two runtime dependencies:

  "dependencies": {
    "@trojs/openapi-dereference": "^1.0.1",
    "js-yaml": "^4.1.0"
  }

The dereference library resolves the $ref pointers inside a specification, which is the step that turns a document full of references into a document a tool can follow. The YAML library parses the YAML form, which is what makes the JSON and YAML support claim work without a second code path.

So the server fetches a specification, dereferences it, parses it, and returns the parts of it that a tool call asked for, wrapped in the simple language summaries described earlier. There is no persistence layer, no user accounts and no state in the repository. The top-level entries are a .gitignore, the LICENSE, the README, a drawio source file for the architecture diagram, package.json, worker.ts and wrangler.json.

That smallness is the interesting engineering decision. A specification parser is a solved problem, and the value of this project is not the parsing but the registry lookup and the summarisation, both of which live outside this repository. The code here is a thin adapter between an MCP client and a hosted service.

A beta release on a public URL, with the logic hosted elsewhere

The maintenance picture deserves a clear statement, because the release history and the push history disagree.

There is one published release, v1.2.0-beta04, dated 2025-01-27. The repository is not archived and the last push was on 2026-07-07. So the code has been touched in the last three months, while the published artefact has not moved since the start of 2025 and is still labelled beta. Whatever you install from the hosted URL, you are not necessarily running the tip of the main branch, and the beta label has been on the only release for the whole of that period.

The second structural point is that the intelligence is not in this repository. The identifier resolution goes through oapis.org, the search comes from OpenAPISearch, and the plain language summaries are produced by the service behind the hosted endpoint. So the server is a thin, readable adapter, and the hard part, summarising a specification accurately, is a black box you depend on but cannot inspect from here.

That has two consequences. The privacy question is real: the specification you ask about travels to a third party service, and if your API is not public you should think about whether it belongs in that registry at all. The quality question is also real: a summary that misdescribes an operation is worse than no summary, because the agent will trust it.

The project links a demo post and a Hacker News thread, which are the places to look for how the author has framed the design decisions.

Where it is the wrong tool, and what the alternative approach costs

The clearest limit is the registry dependency. The first step of the process is working out the OpenAPI identifier, and that identifier comes from oapis.org. A private service described only by a specification on your own network has no registry entry, and the server has no documented way to accept a local file or a raw URL. If your API is internal, this server is not for you.

There is a second limit in the same place. The alternative approach is to give the agent the specification directly, as a file in the repository or a path the client can read, and let the client parse it. The difference in approach is that your version does the parsing locally with no registry and no third party service, at the cost of a large document in the context window and a model that has to navigate it. This server trades that for a summarised view, which is better when the API is big and public, and worse when the API is small, private, or needs exact schema fidelity.

The licence is MIT, so running the worker yourself, forking it, or pointing a client at an instance you host carries no copyleft obligation. The host is at openapi-mcp.openapisearch.com, the homepage is openapisearch.com, and the architecture diagram is in the repository as openapi-mcp.drawio.png if you want to see how the pieces are meant to fit together.

So the decision comes down to one question: is the API you want to explore already in the registry, and are you content for its specification to be summarised by a service you do not run? If both answers are yes, this is a small, legible piece of infrastructure that does one job. If either is no, the file based route is the one to build on.

Editorial conclusion

Use openapi-mcp-server if your API is indexed in the oapis.org registry and you want an agent to understand its endpoints by name rather than by reading a large specification, and if you are comfortable pointing the client at a hosted MCP URL. Do not use it for a private or internal specification that is not in the registry, or as a substitute for a local copy of the schema in your own repository. Before you adopt it, read worker.ts and wrangler.json to see exactly what the server does with the specification, check whether the only release, v1.2.0-beta04, is close enough to what you need, and confirm that summarising your API through a third party service is acceptable for your data.

Frequently asked questions

Official sources

1. janwilmake/openapi-mcp-server on GitHub
2. License: MIT
3. Project website
4. README
5. Releases