Skip to content
openapi-mcp

CLI options

Every openapi-mcp-generator command-line flag, with aliases, defaults and examples.

By Updated

bash
openapi-mcp-generator --input <path-or-url> --output <dir> [options]

Options#

Option Alias Description Default
--input -i Path or URL to the OpenAPI specification (YAML or JSON) Required
--output -o Directory to write the generated MCP project to Required
--server-name -n Name of the MCP server (package.json name) OpenAPI title or mcp-api-server
--server-version -v Version of the MCP server (package.json version) OpenAPI version or 1.0.0
--base-url -b Base URL for API requests. Required if the OpenAPI servers list is missing or ambiguous Auto-detected if possible
--transport -t stdio, web, streamable-http or cloudflare-worker stdio
--port -p Port for web-based transports 3000
--default-include Default for x-mcp filtering. true includes operations by default, false excludes them true
--allow-external-refs Allow resolving external http(s) $ref references. Off by default to prevent SSRF during parsing false
--max-tool-name-length Maximum length of generated tool names. Longer names are truncated with a hash suffix 64
--header-passthrough Comma-separated inbound header names to forward to the upstream API (web, streamable-http, cloudflare-worker). Enables per-user API keys none
--inbound-auth Inbound auth for HTTP transports: none or bearer. With bearer, clients must send Authorization: Bearer <token> (MCP_AUTH_TOKEN) none
--insecure -k Skip TLS certificate verification in the generated server false
--generate-lib Export main() instead of running it, without signal or cleanup wiring false
--custom-auth Generate an editable src/auth.ts hook (applyCustomAuth) that runs before built-in auth false
--oauth-creds-in-body Send OAuth2 client credentials in the token request body instead of a Basic Authorization header false
--include-tags Comma-separated tags: generate only operations with one of them (case-insensitive) all
--exclude-tags Comma-separated tags: skip operations with any of them. Exclusions win over inclusions none
--include-operations Comma-separated operationIds or tool names to generate. Combined with --include-tags as a union all
--exclude-operations Comma-separated operationIds or tool names to skip. Exclusions win over inclusions none
--output-schema Declare each tool's outputSchema from its 2xx JSON response schema (objects only) and reject responses that do not match it false
--force Overwrite existing files in the output directory without confirmation false

Runtime configuration#

  • The generated server reads API_BASE_URL from the environment (.env), which overrides the base URL taken from the spec's servers list.
  • An operation's servers[0] wins over its path item's, which wins over the root server, with server variables set to their defaults. An absolute operation or path server is used even when API_BASE_URL is set; a relative one resolves against the active base URL ("v2" appends a segment, "/v2" replaces the path).
  • The port resolves from --port, then the PORT environment variable, then 3000.
  • MCP_AUTH_TOKEN, or comma-separated MCP_AUTH_TOKENS for rotation, holds the inbound token when you generate with --inbound-auth bearer.
  • MCP_ALLOWED_ORIGINS (Node HTTP servers) lists extra browser origins allowed to call the server, comma-separated. Loopback origins are always allowed.
  • MCP_ALLOW_MISSING_CREDENTIALS=true sends requests without credentials when none of an operation's security requirements can be satisfied, instead of failing closed.
  • MCP_PLAYGROUND=off (Node), or the MCP_PLAYGROUND var set to "off" (Worker), stops serving the browser playground at /.

.env is loaded with Node's built-in process.loadEnvFile() from the working directory; variables already set in the environment win.

Examples#

bash
# stdio (default)
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir

# Web server with SSE
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir --transport=web --port=3000

# Streamable HTTP, protected by a bearer token
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir --transport=streamable-http --inbound-auth bearer

# Cloudflare Worker
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir --transport=cloudflare-worker

# Remote spec, explicit base URL, only operations marked x-mcp: true
openapi-mcp-generator -i https://example.com/openapi.yaml -o ./api-mcp -b https://api.example.com --default-include false

# Only the pets and store tags, without deletePet
openapi-mcp-generator -i openapi.json -o ./my-mcp --include-tags pets,store --exclude-operations deletePet
PreviousQuickstartNext Transports