Sezzlee OpenAPI

@sezzlee/openapi-mcp

MCP server that exposes an OpenAPI (Swagger 2.0 / OpenAPI 3.0–3.2) document as sezzlee's search-first tool catalog — search_tools, load_tool, invoke_tool, read_result — over a remote backend, calling it with fetch.

Status: 1.0.0, stable. Install with npm install -g @sezzlee/openapi-mcp or run it with

npx -y @sezzlee/openapi-mcp; the binary is sezzlee-openapi.

How this differs from the embedded SDK

The NestJS SDK sits inside your backend process: it discovers endpoints from your own controllers/routes and replay each MCP call through your existing pipeline, so your authentication and authorization run exactly as they do today.

openapi-mcp is a separate service. It has no access to a backend's process or pipeline — it reads the backend's OpenAPI document to learn what operations exist (the ingestion rules), and calls the backend over the network for every invocation, attaching a credential it resolves itself (how a credential is chosen and written). This is the only path for a backend that has no embedded SDK integrated into it.

Everything an embedded SDK declares in code, a document declares in one x-sezzlee extension per operation, and a host that cannot edit the document declares under operations in this config: selection, tool name, prefix, behaviour hints, argument curation, variants, families, search terms and revisions (the x-sezzlee extension). A backend that routes many capabilities through one endpoint (POST /Rest/InvokeDynamicMethod/{methodId}) lists them in that operation's x-sezzlee.family; each member becomes its own tool, with its own name, description and body, and the dispatch key stays hidden.

Quick start

The server reads its configuration from the file named by SEZZLEE_OPENAPI_CONFIG. Build the package first (this repository never runs @sezzlee/core's consumers against a stale dist):

pnpm turbo run build --filter=@sezzlee/openapi-mcp

A minimal config — a local document, opt-in selection so at least one operation is exposed, default stdio transport:

{

"source": "./openapi.json", "selection": { "default": "include" } }

SEZZLEE_OPENAPI_CONFIG=/absolute/path/to/config.json node packages/servers/openapi-mcp/dist/cli.js

source is either a path (resolved relative to the config file's own directory) or an http(s):// URL. On startup the server ingests the document, builds the catalog, prints a one-line-per-diagnostic-code summary to stderr, and then serves stdio or listens for streamable HTTP, depending on transport.kind.

A config that fails validation, or that names an environment variable that is not set, stops the process with a message on stderr and exit code 2. A document that ingests with a fatal diagnostic, or a catalog with a fatal diagnostic (name_collision, invalid_name, ambiguous_selection, …), stops it with exit code 1.

Configuration

All keys below are read from the SEZZLEE_OPENAPI_CONFIG JSON file and validated with a zod schema (src/platform/config.ts) that rejects unknown keys.

| names | record\ | {} | Overrides a tool's name; the value must match `^[a-z][a-z0-