openapi-explorer-mcp

An MCP server for any OpenAPI 3 spec. It lets an AI agent find endpoints, inspect request and response shapes without loading a megabyte of JSON, generate TypeScript types, and call endpoints — with credentials mapped to the security schemes the spec already declares.

Unlike servers that turn every operation into its own tool, this one stays small: a handful of tools that explore the spec and one generic caller.

Tools

Related MCP server: Swagger MCP Server

Output

The exploring tools answer in plain text — an agent reads it as well as JSON and it costs a fraction of the tokens:

api_search(query: "equity history")

3 of 3 · accounts 1, admin/accounts 1, admin/hedge 1
GET /accounts/{accountId}/equity-history — Get the equity history of the trader account [bearer] (path: accountId; query: timestamp?, duration?)
GET /admin/accounts/account-equity-history — Get the equity history of the trader account [x-admin-token|bearer] (query: accountId, timestamp?, duration?, changeFraction?)
GET /admin/hedge/dashboard/user-history — User equity and OI history [x-admin-token|bearer] (query: userId, timeframe, from?, to?) · field initialEquity, currentEquity

Each line carries the auth alternatives, destructive, body and deprecated flags and the parameter names; · field … says the endpoint was found through a field of its request or response. Schemas render as a compact pseudo-type: a format or a well-known pattern is named (string (uuid)), enums are listed up to 20 values, descriptions are cut at a word.

api_get, api_request, api_credentials, api_spec_info and api_call_log answer in compact JSON.

Search

Endpoints and schemas are indexed with MiniSearch on first use. Words are split on punctuation, camelCase and digits (closeReason also matches as a whole), stop words are dropped, and each word is stemmed by its script — English with Porter, Russian with Snowball — so no language setting is needed. Queries match whole words, prefixes and one typo; a compound identifier outweighs its parts. Results are ranked by BM25 with field weights (path and summary first, then operationId, danger reason, description, parameters, schema names and body fields) and hits scoring below 30% of the best one are dropped. An exact key, path or operationId always comes first. When nothing matches, the answer says how to search differently and lists similar words from the spec.

Narrowing responses

fields keeps only the listed paths of a response; [] stands for every element of an array, and on an array body a path applies to each element. max_items cuts every array and reports the original lengths:

api_get(endpoint: "GET /admin/markets", fields: ["id", "settings.isCloseOnly"], max_items: 3)
{"key":"GET /admin/markets",…,"arrays":{"[]":157},"body":[{"id":"…","settings":{"isCloseOnly":false}},…]}

Without max_items, a response over OPENAPI_MAX_RESPONSE_CHARS gets its arrays cut to 20, 5 or 1 items until it fits, with a note; only then is the text truncated.

Configuration

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["-y", "openapi-explorer-mcp"],
      "env": {
        "OPENAPI_SPEC_URL": "https://api.example.com/openapi.json",
        "OPENAPI_BASE_URL": "https://api.example.com",
        "OPENAPI_AUTH_X_API_KEY": "${MY_API_KEY}",
        "OPENAPI_SERVER_NAME": "my-api"
      }
    }
  }
}

Authentication

The server doesn't invent headers — it reads them from the spec. components.securitySchemes says where a secret goes, and each operation's security says which schemes it accepts. A scheme takes its value from the first of three places that has one:

Permanent credentials — a static admin token, a service API key — belong in the environment: they stay out of the conversation. The variable name is the scheme name upper-cased with every other character replaced by _: x-admin-token → OPENAPI_AUTH_X_ADMIN_TOKEN, bearer → OPENAPI_AUTH_BEARER. A header every call must carry, whatever the spec says, goes to OPENAPI_HEADER_<NAME>.

Credentials the model supplies — a token it just obtained, a key the user pasted into the chat — go through credentials or api_credentials. Keys are scheme names as api_spec_info lists them; an apiKey scheme also accepts its header, query or cookie name, so X-Api-Key finds a scheme named ApiKeyAuth. When the spec declares no security schemes at all, the keys are sent as plain headers.

api_request(method: "POST", endpoint: "POST /auth/login", body: { … })
api_credentials(set: { "bearer": "<accessToken from the response>" })
api_get(endpoint: "GET /me")

When a call with a credential gets 401, the response says so in note.auth: obtain a fresh value and set it again.

Placement. Whatever the source, the value goes where the scheme says:

Which scheme a call uses. security is a list of alternatives. With as: "auto" (the default) the server takes the first alternative whose schemes all have credentials, from any source. as can also name a scheme to force it, or be "anonymous". When nothing is available, a GET is sent anonymously with a note (many GET endpoints declare auth but also answer without it); any other method fails and names every way to supply the credential.

What keeps credentials safe

• Credentials go only to the base URL. The origin of every request is checked against it before sending, and path parameters are URL-encoded, so a path can't redirect a request elsewhere.

• Credentials from the environment need OPENAPI_BASE_URL set explicitly: a server configuration is long-lived and often shared, while the spec's servers comes over the network. Credentials the model supplies go to the base URL that api_spec_info and api_credentials report — OPENAPI_BASE_URL, or the first server of the spec.

• Tool output and the call journal never contain values: they name the scheme and where its credential came from, e.g. bearer (session). A value the model supplies is part of the conversation by nature — keep secrets that must not be there in the environment.

Danger rules

Every non-GET operation is write, and destructive when it is a DELETE or its path contains drop, purge, reset, destroy, bulk or broadcast. api_request refuses destructive operations without confirm_danger: true. OPENAPI_DANGER_FILE adds exact operations and path words:

{
  "operations": {
    "POST /orders": "creates a real order"
  },
  "pathPatterns": ["close", "withdraw"]
}

Development

npm install
npm run typecheck
npm run build      # tsc into dist/
npm run smoke      # stdio checks against scripts/fixtures/pets.json and a local HTTP server, no internet
npm run check      # all three
npm run smoke:package  # packs the tarball, installs it in a clean directory and runs the smoke there

npm publish runs check and smoke:package first. The package depends on TypeScript 5.9 directly: the type generator declares TypeScript as a peer dependency, and without the pin npm installs TypeScript 7, whose JavaScript API the generator can't use.

Bench

npm run bench -- <queries.json> runs a server against a query file and reports search quality (top-1/5/10 and MRR by kind of query), latency, and the tokens of every response and of the tool list (o200k, as a proxy for comparing formats). The file holds env for the server, queries with the endpoints each should find, and calls to measure:

{
  "env": { "OPENAPI_SPEC_URL": "../../fixtures/pets.json" },
  "queries": [{ "q": "list pets", "expect": ["GET /pets"], "kind": "plain" }],
  "calls": [{ "label": "endpoint", "tool": "api_endpoint", "args": { "endpoint": "GET /pets" } }]
}

Relative paths resolve against the file and ${VAR} expands from the environment. --spec overrides the spec — use a saved snapshot to compare runs; --server "npx -y openapi-explorer-mcp@0.1.0" measures another version; --json saves the report and --compare prints the difference with a saved one. scripts/bench/queries/pets.json is the example.

License

MIT — see LICENSE.