A spec with hundreds of operations would flood the tool list if each became its own tool; the discover-then-call shape keeps the advertised surface at two regardless of how large the API is, at the cost of one extra round trip when the model does not yet know the operation ID. The `--filter` flag is the lever worth using early — pointing at a large public API and restricting to the tag you care about keeps the discovery response manageable.
A generic runner that turns an OpenAPI 3.x specification into a callable surface. Instead of a bespoke MCP server per API, you give it a spec URL or file and it exposes a discover-then-call pair; when the spec changes, the callable operations change with it.
- Every operation in the spec listed and grouped by tag, with operation IDs, methods, paths and parameters — and generated operation IDs when the spec omits them — `list_endpoints`
- Any operation executed by operation ID with path, query, header and body parameters resolved, auth and custom headers attached, and the response returned — `call_endpoint`
- JSON or YAML specs, local or remote, with `$ref` schemas dereferenced before the operations are registered
- A narrowed surface when you want one: `--filter` exposes only endpoints matching a path, tag or operation ID, `--server-url` overrides the base URL from the spec, and `--header` adds a repeatable custom header
Node.js 18+ and an OpenAPI 3.x spec, JSON or YAML, as a local file or a URL. The package is `mcp-openapi-runner` (1.1.0), launched over stdio with `npx -y mcp-openapi-runner --spec <url-or-path>`. Credentials for the target API go in the server's environment: `OPENAPI_BEARER_TOKEN` for bearer auth, `OPENAPI_API_KEY` with an optional `OPENAPI_API_KEY_HEADER` (default `X-Api-Key`), or `OPENAPI_BASIC_USER` and `OPENAPI_BASIC_PASS` for basic auth.
One command — npx mcp-openapi-runner --spec https://petstore3.swagger.io/api/v3/openapi.json