list_endpointsLABSCO SUMMARY
Two tools instead of a tool per endpoint.
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.
What it is
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.
What you get
- 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
$refschemas dereferenced before the operations are registered - A narrowed surface when you want one:
--filterexposes only endpoints matching a path, tag or operation ID,--server-urloverrides the base URL from the spec, and--headeradds a repeatable custom header
Requirements
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.
Setup effort
One command — npx mcp-openapi-runner --spec https://petstore3.swagger.io/api/v3/openapi.json
USE CASES
01
Making an internal API callable without writing a server
Point the runner at your service's own OpenAPI document and an API key, and the endpoints are available to the assistant immediately.
02
Working against a large public API without drowning in tools
Restrict the exposed surface to the tag or path prefix you need, then discover and call within that slice.
03
Testing against staging instead of production
Keep the published spec but override the base URL so the same operations run against a local or staging host.
04
Keeping the tool surface current as the API evolves
Re-read the spec rather than maintaining hand-written tool definitions, so a new endpoint is callable as soon as it is documented.
2 tools
Listed in project docs. Your client may show a different list.
call_endpointBEFORE YOU INSTALL
What to know first
Tools you get
2 tools named in the project's documentation.
Requires
- npx on PATH
- Node.js 18+
Where it runs
All 4 documented clients run the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
npx mcp-openapi-runner --spec https://petstore3.swagger.io/api/v3/openapi.jsonMCP Clients
Claude Desktop, Claude Code, Cursor, Cline
JSON
{
"mcpServers": {
"petstore": {
"command": "npx",
"args": [
"-y",
"mcp-openapi-runner",
"--spec",
"https://petstore3.swagger.io/api/v3/openapi.json"
]
}
}
}
