Installation & usage

npx docfy-mcp --spec/--url, registering .mcp.json, --header for authenticated specs.

Requirements

Published on npm — no clone, no build. The only requirement is Node itself; npx fetches docfy-mcp on first use.

Quick start

bash
# from a static file
npx docfy-mcp --spec ./openapi.json

# from a locally running NestJS server
npx docfy-mcp --url http://localhost:3000/docs-json

--url fetches the spec directly rather than delegating to swagger-parser's own HTTP resolver — that resolver's SSRF guard blocks localhost/private addresses by default, which would break the most common case here: pointing at a local NestJS dev server.

Registering as an MCP server

json
{
  "mcpServers": {
    "docfy": {
      "command": "npx",
      "args": ["-y", "docfy-mcp", "--url", "http://localhost:3000/docs-json"]
    }
  }
}

For specs behind auth, repeat --header as many times as needed.

bash
npx docfy-mcp --url https://api.example.com/api-json --header "Authorization: Bearer xyz"

Options

OptionDefaultDescription
--spec <path>—Local OpenAPI JSON/YAML file
--url <url>—URL to fetch the spec from
--header <name: value>noneRepeatable — extra header sent with --url requests

Troubleshooting a 404

The OpenAPI JSON path isn't a fixed convention — it depends on what your project passed to SwaggerModule.setup().

If --url 404s, docfy-mcp probes a handful of common sibling paths on the same origin (/api-json, /docs-json, /swagger-json…) and suggests any that parse as a real OpenAPI document.