openapi-lookup-mcp

MCP server that lets AI coding agents such as Claude Code and Cursor read one endpoint or schema of an OpenAPI or Swagger spec instead of the whole file. Real-world specs often run to millions of tokens and do not fit in a context window; with this server the agent searches the spec, gets back a compact summary with every $ref already resolved, and keeps working.

• Over 99% fewer tokens than reading the spec: finding and reading one endpoint costs about 2,000 tokens on the 2.8-million-token GitHub spec.

• 57–68% smaller than the same endpoint in YAML, with nested schemas resolved in a single call.

• Built-in search that handles typos, word forms and identifiers such as listJobMatches, with no model or embeddings.

• Local files or remote URLs, OpenAPI 3.x and Swagger 2.0, with caching and automatic refresh.

Installation

Requires Node.js 18 or newer. From the root of your project:

npx -y @harborkit/openapi-lookup-mcp init https://example.com/api-docs/swagger.yaml

Then open the project in Claude Code or Cursor and approve the new api-spec server when prompted.

The command writes .mcp.json (Claude Code) and .cursor/mcp.json (Cursor), keeping any servers already configured there. Running it again updates the entry, for example with a new URL. If a different server is already registered as api-spec, nothing is changed: add --name <other name> to keep both, or --force to replace it.

npx -y @harborkit/openapi-lookup-mcp init https://example.com/api-docs/swagger.yaml --name billing-api

Manual configuration

If you prefer to configure the server yourself, add a block like this to .mcp.json (or the equivalent file for your editor):

{
  "mcpServers": {
    "api-spec": {
      "command": "npx",
      "args": ["-y", "@harborkit/openapi-lookup-mcp@0.2.0"],
      "env": {
        "OPENAPI_SPEC_URL": "https://example.com/api-docs/swagger.yaml"
      }
    }
  }
}

The same server can also be launched directly, with the spec as an argument or in OPENAPI_SPEC_URL:

npx -y @harborkit/openapi-lookup-mcp https://example.com/api-docs/swagger.yaml

Environment variables

Related MCP server: code-context

Example

GET /users/{id} — Get a user
auth: bearerAuth (http bearer JWT)
path:
  id: string
query:
  view?: "short" | "full" (default: "short") — level of detail
responses:
  200 — success: user
    header X-RateLimit-Remaining?: integer
  404 — not found

user = {
  id: integer (readOnly)
  nickname?: string | null (maxLength: 30)
  team?: team
}

team = {
  name: string
  members?: user[]
}

spec read just now from spec.yaml

See Token cost for how this compares to reading the spec.

Token cost

Measured on the GitHub REST and Stripe specs with the 111 queries of the search benchmark. Tokens are estimated as characters / 4; no agent was involved, so the agent's own reasoning is not counted.

Without the tool, an agent has three options, all worse on a large spec:

• Read the whole spec. Neither of these specs fits in a context window.

• Grep a local file and read pieces of YAML. The same endpoint with its schemas is about three times larger in YAML than in the compact summary, and following each $ref by hand takes several turns.

• Fetch a remote spec. A URL cannot be grepped, so the agent downloads everything or works from a lossy summary.

The queries above target popular, large endpoints. Across every endpoint of the GitHub spec the median summary is about 490 tokens.

When it does not pay off: on a small spec such as Petstore (about 5,000 tokens in full), reading the file once is affordable. The tool still wins for a handful of lookups, but an agent that needs most of the endpoints spends about the same either way.

Supported inputs

• OpenAPI 3.x

• Swagger 2.0

• Local files (.yaml, .yml, .json)

• Remote URLs

• $ref imports from other files and local fragments, within the limits in Referenced documents

• Schema resolution for nested objects and arrays

Tool reference

search_endpoints

Ranked keyword search over every endpoint of the spec. It needs no model, embeddings or extra dependency: the index is built in memory the first time the spec is searched (about 0.2 s for the GitHub spec) and a query takes a few milliseconds.

What is searched, from most to least important:

• path, summary and operation id

• HTTP method, tags, parameter names and the schemas the endpoint uses

• description, and the property names of its request and response bodies

• schemas nested one level deeper, path parameters and parameter descriptions

How a query is read:

• Filler words such as I, need, how or the are ignored.

• Word forms match each other: create, creates, created and creating; repository and repositories.

• Identifiers are split into their words, so listJobMatches, job_matches and job matches are the same query.

• Action words match the HTTP method and their synonyms: retrieve or show → GET, add or new → POST/create, edit or modify → PATCH/PUT/update, remove → DELETE.

• Abbreviations match the words they start: repo finds repository.

• Typos are corrected when a word is not in the spec at all, and the answer says so. Only words of five letters or more are corrected, and never by changing the first letter.

How results are ranked:

• A word that is rare in the spec counts for more than one that appears in most endpoints.

• A match in a short, specific text counts for more than one in a long text, so create issue ranks POST …/issues above POST …/issues/{issue_number}/assignees.

• An endpoint that misses a word of the query is ranked lower, and more so when the missing word is a rare one. When not even the best result has every word, the answer starts with a line that says so.

• Endpoints that score far below the best one are left out, so a precise query gets a short answer.

• At most 10 endpoints are returned, about 200 tokens. When more are relevant the answer ends with … N more; pass limit (up to 50) to list everything about a resource.

> search_endpoints { "query": "create teams" }

POST /teams — Create a team

> search_endpoints { "query": "creating a tema" }

Read "tema" as "team".
POST /teams — Create a team

> search_endpoints { "query": "nickname invoices" }

Nothing in the spec mentions "invoices"; searched for the other words.
GET /users/{id} — Get a user
POST /teams — Create a team

Keywords still work better than long sentences, and the search matches words, not meanings: it does not know that "bookmark" means "star". The tool description tells the agent to search again with the API's own terms when the endpoint it needs is not listed; with short answers, a second search costs less than one long answer. See Search quality for measurements.

get_endpoint

Accepts:

• a template such as /users/{id}

• a concrete path such as /users/42

• a full URL such as https://example.test/api/users/42?x=1

The server removes the API base path when present before matching. raw: true returns the original spec YAML for that endpoint, while refresh: true forces a fresh fetch before answering.

get_schema

Looks up a schema by name case-insensitively and suggests similar names when no exact match exists. It returns:

• the schema definition

• referenced nested schemas

• the endpoints that use the schema directly or transitively

Schemas that live in referenced documents can be looked up the same way. raw and refresh behave as in get_endpoint.

> get_schema { "name": "team" }

team = {
  name: string
  members?: user[]
}

user = {
  id: integer (readOnly)
  nickname?: string | null (maxLength: 30)
  team?: team
}

team is used directly by:
  POST /teams — Create a team
used through other schemas by:
  GET /users/{id} — Get a user

Reading the output

• name? marks an optional property or parameter; name without ? is required. As in OpenAPI, a property is optional unless the schema lists it in required.

• Constraints and flags appear in parentheses after the type, for example limit?: integer (minimum: 1, default: 20) — rows per page.

• Supported keywords include default, readOnly, writeOnly, deprecated, minimum, maximum, minLength, maxLength, pattern, minItems, maxItems and uniqueItems. Examples are not shown; use raw: true to see them.

• A line starting with // above a schema is that schema's description.

• discriminator shows the discriminator property and its mapping, for example discriminator: kind (dog → dog, cat → cat).

• A | B is a union, A & B is an intersection, and T | null is a nullable type.

• Unresolvable references are reported as unresolved reference … instead of being silently dropped.

• auth: shows how each scheme is sent, for example bearerAuth (http bearer JWT) or apiKey (apiKey in header "X-API-Key"). a + b means both are required, a | b means either one, and none means the endpoint can be called without credentials.

• Response headers appear under each response as header Name?: type.

• Schemas the endpoint references directly are always shown. Schemas nested inside them are expanded until they add up to about 4,000 tokens; the rest are named in a Not expanded … line and can be read with get_schema.

• Every answer ends with the age and source of the spec, and with a warning when a referenced document could not be loaded.

Referenced documents

A spec decides which other documents get loaded, so those references are restricted by default:

• A remote spec can only load documents from its own origin (same scheme, host and port). To allow other hosts, list them in OPENAPI_ALLOWED_REF_HOSTS (comma-separated, or * for any). A remote spec can never read local files.

• A local spec can only load files inside the folder the server runs in or the spec's own folder, after resolving symlinks. Set OPENAPI_REF_ROOT to allow a different folder. Remote documents also need OPENAPI_ALLOWED_REF_HOSTS.

• Referenced documents are limited to 10 MB each, 15 seconds per download and 50 documents in total. They are read four at a time and redirects are not followed.

• The spec itself is limited to 50 MB and 30 seconds.

A document that is not loaded does not stop the server. Its references are shown as unresolved reference … and every answer ends with the reason, for example referenced documents not loaded: https://other.test/models.yaml (host other.test is not allowed; …).

Caching and freshness

• Remote specs are cached for 6 hours in memory and in ~/.cache/openapi-lookup-mcp.

• When a search or endpoint lookup returns no match, the server refreshes the spec before answering, with a cooldown of at most 5 minutes.

• Local files are re-read whenever they change.

• Referenced files are re-read only when the main spec changes.

• Every result includes the age of the spec it was read from.

Benchmark

The project includes a benchmark script:

npm run benchmark

This renders every endpoint and schema for a set of public specs, fails if any render throws, and compares the compact summary against the raw YAML for the same endpoint. You can also pass your own spec URLs or local files to benchmark those instead.

Measured on 2026-11-10. Tokens are estimated as characters / 4. The Compact / raw ratio compares the total size of all endpoints in both formats.

Search quality

npm run benchmark:search            # add "-- --misses" to list the queries that fail

This runs the 111 queries in scripts/search-queries.js against the GitHub and Stripe specs. Each query names the endpoint an agent would want back. The report gives, per query type, how often that endpoint is among the first 1, 5 and 10 results (Top-1, Top-5, Top-10), the mean reciprocal rank (MRR, the mean of 1 / rank) and the mean number of endpoints in an answer.

Measured on 2026-11-10 with version 0.2.0. A search answer is about 220 tokens on the GitHub spec and 180 on Stripe (median).

Paraphrases remain the weak spot: a query whose words are not in the spec ("bookmark a repository", "tag an issue" for labels, "reverse a payment" for refunds) cannot be found by matching words. The query set is hand-written and was also used to tune the ranking, so these figures are optimistic; one query moves a row by 3 to 10 points.

Limitations

• Search matches words, not meanings. A query with none of the API's own terms ("bookmark" for star, "chargeback" for dispute) will not find the endpoint; the agent has to search again.

• Search understands English only. Filler words, word forms and action synonyms are English.

• Large schema graphs are cut. Nested schemas beyond about 4,000 tokens are named, not expanded, so reading a deeply linked model can take several get_schema calls.

• Examples are not shown in the compact summary; raw: true returns them.

• Constraints of array items (for example the minLength of each element) are not shown; only those of the array itself are.

• Referenced documents behind a redirect are not loaded, and a referenced file that changes is only re-read when the main spec changes.

• Not covered: callbacks, links, webhooks and the style/explode serialization of parameters.

Development

npm install
npm test
npm run benchmark
npm run benchmark:search
node src/server.js path/to/spec.yaml

Source layout:

Tests use Node's built-in runner and need no network, except test/references.test.js, which starts local HTTP servers. The benchmarks download public specs. Changes are listed in CHANGELOG.md.

Notes

• The server expects Node.js 18 or newer.

• The package name is @harborkit/openapi-lookup-mcp.

• The generated MCP server name is api-spec unless --name is given.

• OPENAPI_SPEC_URL is the environment variable used when launching the server directly.