Skip to main content

@powerduck/openapi-mcp-server Introduction

@powerduck/openapi-mcp-server converts an OpenAPI document into a running MCP (Model Context Protocol) service. It generates Tools from operations, Prompts from the API's metadata and operations, and Resources from the API catalog, then serves them over the MCP protocol with a built-in admin Web UI.

  • Package name: @powerduck/openapi-mcp-server
  • Version:
  • License: MIT
  • Node engine: >=20.11
  • CLI binary: openapi-mcp
  • Module format: dual ESM and CommonJS builds with bundled type declarations.

It is built on @powerduck/openapi-parser for validation and dereferencing and on @modelcontextprotocol/sdk for the protocol.

What it generates​

  • Tools — one MCP tool per OpenAPI operation, with full parameter serialization (path/query/header/cookie styles and explode rules), request-body encoding (JSON, form-urlencoded, multipart, text, binary), and MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint).
  • Prompts — global prompts (spec_overview, integration_guardrails) plus per-operation prompts (explain_*, plan_*, sample_*).
  • Resources — fixed catalog resources such as openapi://spec/summary, openapi://catalog/tools, openapi://spec/document.

Transports​

  • stdio — startStdioServer() serves one document to a local MCP client (Claude Desktop, editor integrations).
  • web (HTTP) — attachSseRoutes() mounts the Streamable HTTP transport at /mcp and the legacy SSE transport at /sse on your own Express app. For session limits, idle reaping, CORS and DNS-rebinding protection, use startAdminServer() which wraps the internal transport with all of those options.

Admin runtime​

startAdminServer() starts an Express app that serves:

  • the Web admin console (upload/paste a spec, inspect tools/prompts/resources, view running services and request logs),
  • the MCP HTTP transports,
  • API-key authentication, request logging with sensitive-header redaction, and optional state persistence.

Installation​

npm install @powerduck/openapi-mcp-server

Quick start​

openapi-mcp serve --transport web --port 3000 --api-key your-admin-key

Next steps​

License​

MIT.