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.

A credentials entry is keyed by the security scheme name it satisfies; a tokenExchange.schemes entry marks that same scheme as satisfied by the exchanged token instead. credentials values are never inlined — only a reference to an environment variable — so a config file can be committed and shared.

Rules

• Only src/net/fetch.ts reaches the network. It is the one place the host allowlist, the manual redirect handling and the byte cap are applied; src/transport/http.ts may use node:http only to listen, never to call out. Redirects are never followed — a followed redirect could carry a request, and its credential, to a host the allowlist never approved.
• Only src/platform/files.ts touches the filesystem. A file the document references through an external $ref, or named by source, is checked against the directory the document was read from on its realpath, so neither a ../ segment nor a symbolic link can escape it.
• The caller's MCP token is never forwarded to the backend. Its audience is this server, not the backend; forwarding it would bypass the backend's own audience check. On the http transport with tokenExchange configured, the caller's token is exchanged (RFC 8693) for a backend-scoped token at the transport's bearer gate, and only the exchanged token reaches invoke_tool.
• An http transport without tokenExchange authenticates no caller, so it may only bind a loopback host (127.0.0.1, ::1, localhost); otherwise the operator's static credentials would be reachable from the network. Configuring tokenExchange on the stdio transport is likewise refused (token_exchange_requires_http) — there is no caller token on stdio to exchange.
• A reload never widens egress. reload re-reads only the document, never the config, and the hosts the first catalog may call are the ceiling for every later one: a document whose servers move to a host outside it, from https to plain http, or that sends a credential to a plain-http origin that did not carry it before, is refused (widens_egress). A refused document, one with a fatal diagnostic, or one that cannot be read keeps the running catalog. A committed reload advances the catalog generation stamped on every meta-tool and sends tools/list_changed. A tool loaded before a reload answers unknown_tool if it is gone and tool_changed to a call pinned to its old version.
• Visibility is not enforcement: an operation's security says which credential a call needs, not which caller may make it, so the catalog reports every operation's identity as unknown unless its document says security: [].

Development

pnpm turbo run build --filter=@sezzlee/openapi-mcppnpm turbo run lint --filter=@sezzlee/openapi-mcppnpm turbo run check-types --filter=@sezzlee/openapi-mcppnpm turbo run test --filter=@sezzlee/openapi-mcp

Run these through Turbo, not pnpm --filter @sezzlee/openapi-mcp <task> — the bare filter skips dependsOn: ["build"] and the test task would run against a stale dist.

test/ holds unit suites that need no environment variables, plus one gated suite:

• acceptance.spec.ts — skipped unless SEZZLEE_OPENAPI_ACCEPTANCE_DOC names a path to a real backend's OpenAPI document. The document itself never enters the repository; the suite ingests it, builds a catalog, asserts there is no fatal diagnostic, and prints the diagnostic summary instead of pinning a snapshot that would copy that backend's surface into the tree. SEZZLEE_OPENAPI_ACCEPTANCE_DOC is declared in this package's turbo.json test task so Turbo passes it through.