Command-Line Options

This page provides a complete reference for all command-line options available in openapi-mcp.

Usage

The basic command-line syntax for openapi-mcp is: 

openapi-mcp [flags] <openapi-spec-path>

The OpenAPI spec path is a required argument, and it should point to a valid OpenAPI 3.x YAML or JSON file.

Commands

openapi-mcp supports several commands for different use cases:

Server Mode (Default)

openapi-mcp [flags] <openapi-spec-path>

Starts an MCP server that exposes all operations from the OpenAPI spec as tools. This is the default mode.

Validate Command

openapi-mcp [flags] validate <openapi-spec-path>

Validates the OpenAPI spec and reports critical issues that would prevent proper MCP tool generation. This includes:

  • Missing operationId fields (required for tool names)
  • Schema validation errors
  • Basic structural issues

Exits with non-zero status code if critical issues are found, making it perfect for CI/CD pipelines.

Lint Command

openapi-mcp [flags] lint <openapi-spec-path>

Performs comprehensive linting of the OpenAPI spec with detailed suggestions for best practices. This includes:

  • Missing summaries and descriptions
  • Untagged operations
  • Parameter naming and type recommendations
  • Security scheme validation
  • API design best practices

Provides actionable feedback to improve your API specification quality. Reports both errors and warnings.

HTTP API Mode

openapi-mcp --http=:8080 validate
openapi-mcp --http=:8080 lint

Both validate and lint commands can run as HTTP services using the --http flag. This creates dedicated REST API endpoints for validation/linting (these endpoints are only available in validate/lint mode, not during normal MCP server operation):

  • POST /validate or POST /lint - Process OpenAPI specs sent in request body
  • GET /health - Health check endpoint

Perfect for integrating into web applications, CI/CD pipelines, or microservice architectures.

Flag Categories

The command-line flags are grouped into several categories:

Server Flags

Flag Environment Variable Description
--http=ADDR - Serve MCP over HTTP instead of stdio.
Example: --http=:8080
Note: In HTTP mode, authentication can also be provided via headers: X-API-Key, Api-Key, Authorization: Bearer <token>, Authorization: Basic <credentials>
--mount /base:path/to/spec.yaml - Mount an OpenAPI spec at a base path (repeatable, can be used multiple times).
Example: --mount /petstore:petstore.yaml --mount /books:books.yaml
By default, this will serve the Petstore API at /petstore (StreamableHTTP), and the Books API at /books. If you use --http-transport=sse, endpoints like /petstore/sse and /petstore/message will be available for SSE clients.
--base-url=URL OPENAPI_BASE_URL Override the base URL for HTTP calls.
Example: --base-url=https://api.example.com

Multi-Mount Example

openapi-mcp --http=:8080 --mount /petstore:petstore.yaml --mount /books:books.yaml

This will serve multiple OpenAPI schemas at different base paths. Each API will be available at its own prefix (e.g., /petstore/sse, /books/sse).

Authentication Flags

Authentication can be provided via command-line flags, environment variables, or HTTP headers (when using --http mode).

Flag Environment Variable Description
--api-key=KEY API_KEY API key for authenticated endpoints.
Example: --api-key=your_api_key
--bearer-token=TOKEN BEARER_TOKEN Bearer token for Authorization header.
Example: --bearer-token=your_token
--basic-auth=USER:PASS BASIC_AUTH Basic auth credentials (username:password).
Example: --basic-auth=username:password

Filtering Flags

Flag Environment Variable Description
--tag=TAG OPENAPI_TAG Only include operations with this tag.
Example: --tag=admin
--include-desc-regex=REGEX INCLUDE_DESC_REGEX Only include APIs whose description matches this regex.
Example: --include-desc-regex="user|account"
--exclude-desc-regex=REGEX EXCLUDE_DESC_REGEX Exclude APIs whose description matches this regex.
Example: --exclude-desc-regex="deprecated"

Output Flags

Flag Environment Variable Description
--extended - Enable extended (human-friendly) output.
Default output is minimal and agent-friendly.
--dry-run - Print the generated MCP tool schemas as JSON and exit.
Useful for debugging and previewing.
--summary - Print operation count summary.
Shows count of operations by tag.

Documentation Flags

Flag Environment Variable Description
--doc=FILE - Write documentation for all tools to this file.
Example: --doc=tools.md
--doc-format=FORMAT - Documentation format: markdown (default) or html.
Example: --doc-format=html
--post-hook-cmd=CMD - Command to post-process the generated tool schema JSON.
Example: --post-hook-cmd='jq . | tee /tmp/filtered.json'

Safety Flags

Flag Environment Variable Description
--no-confirm-dangerous - Disable confirmation for dangerous (PUT/POST/DELETE) actions.
Warning: Use with caution as this can lead to unintended changes.

Examples

Basic Usage

bin/openapi-mcp examples/fastly-openapi-mcp.yaml

This loads the OpenAPI spec, validates it, and starts an MCP server in stdio mode.

Validate OpenAPI Spec

bin/openapi-mcp validate examples/fastly-openapi-mcp.yaml

This validates the OpenAPI spec and reports any critical issues that would prevent proper tool generation. Perfect for CI/CD pipelines to ensure spec quality.

Comprehensive Linting

bin/openapi-mcp lint examples/fastly-openapi-mcp.yaml

This performs detailed linting with suggestions for best practices, including missing summaries, descriptions, tags, and parameter recommendations.

HTTP Validation Service

bin/openapi-mcp --http=:8080 validate

This starts an HTTP server that accepts OpenAPI specs via POST requests to /validate. Returns structured JSON responses with validation results.

HTTP Linting Service

bin/openapi-mcp --http=:8080 lint

This starts an HTTP server that provides comprehensive linting via POST requests to /lint. Perfect for integrating into web applications or CI/CD pipelines.

HTTP Server with API Key

bin/openapi-mcp --http=:8080 --api-key=your_api_key examples/fastly-openapi-mcp.yaml

This starts an HTTP server on port 8080 and configures API key authentication.

Filtering Operations

bin/openapi-mcp --tag=admin --exclude-desc-regex="deprecated" examples/fastly-openapi-mcp.yaml

This includes only operations with the "admin" tag and excludes any operations with "deprecated" in their description.

Generating Documentation

bin/openapi-mcp --doc=tools.md --doc-format=markdown examples/fastly-openapi-mcp.yaml

This generates Markdown documentation for all tools and writes it to tools.md.

Post-Processing

bin/openapi-mcp --dry-run --post-hook-cmd='jq . | tee /tmp/filtered.json' examples/fastly-openapi-mcp.yaml

This generates the tool schemas, passes them through jq for formatting, and saves to a file.

Summary and Dry Run

bin/openapi-mcp --summary --dry-run examples/fastly-openapi-mcp.yaml

This prints a summary of the operations by tag and exits without starting a server.

Next Steps

Now that you understand the command-line options, you can: