Configuration

Server Mode

By default, openapi-mcp runs in stdio mode, but it can also run as an HTTP server:

Flag	Environment Variable	Description
--http=:8080	-	Run as HTTP server on the specified address (e.g., :8080 for port 8080 on all interfaces)

Example:

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

Base URL

Override the base URL defined in the OpenAPI spec:

Flag	Environment Variable	Description
--base-url=URL	OPENAPI_BASE_URL	Override the base URL for HTTP calls

Example:

bin/openapi-mcp --base-url=https://api.example.com examples/fastly-openapi-mcp.yaml

Authentication

Configure authentication for API calls:

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

For more details, see the Authentication page.

By Tag

Include only operations with a specific tag:

Flag	Environment Variable	Description
--tag=TAG	OPENAPI_TAG	Only include operations with this tag

Example:

bin/openapi-mcp --tag=admin examples/fastly-openapi-mcp.yaml

By Description

Include or exclude operations based on their description using regular expressions:

Flag	Environment Variable	Description
--include-desc-regex=REGEX	INCLUDE_DESC_REGEX	Only include APIs whose description matches this regex
--exclude-desc-regex=REGEX	EXCLUDE_DESC_REGEX	Exclude APIs whose description matches this regex

Examples:

# Include only operations with "user" or "account" in their description
bin/openapi-mcp --include-desc-regex="user|account" examples/fastly-openapi-mcp.yaml

# Exclude operations with "deprecated" in their description
bin/openapi-mcp --exclude-desc-regex="deprecated" examples/fastly-openapi-mcp.yaml

Human vs. Agent-Friendly Output

By default, openapi-mcp uses minimal, agent-friendly output. For human-friendly output:

Flag	Environment Variable	Description
--extended	-	Enable extended (human-friendly) output

Example:

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

Note: For machine, agent, or CI usage, do not use --extended. The default output is more suitable for automated processing.

Documentation Generation

Generate documentation for all tools:

Flag	Environment Variable	Description
--doc=FILE	-	Write documentation for all tools to this file
--doc-format=FORMAT	-	Documentation format: markdown (default) or html

Examples:

# Generate Markdown documentation
bin/openapi-mcp --doc=tools.md examples/fastly-openapi-mcp.yaml

# Generate HTML documentation
bin/openapi-mcp --doc=tools.html --doc-format=html examples/fastly-openapi-mcp.yaml

Dry Run and Summary

Print tool schemas or summary without starting a server:

Flag	Environment Variable	Description
--dry-run	-	Print the generated MCP tool schemas as JSON and exit
--summary	-	Print operation count summary

Examples:

# Print tool schemas
bin/openapi-mcp --dry-run examples/fastly-openapi-mcp.yaml

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

Confirmation for Dangerous Operations

By default, openapi-mcp requires confirmation for dangerous operations (PUT/POST/DELETE). To disable this behavior:

Flag	Environment Variable	Description
--no-confirm-dangerous	-	Disable confirmation for dangerous actions

Example:

bin/openapi-mcp --no-confirm-dangerous examples/fastly-openapi-mcp.yaml

Note: Disabling confirmation can lead to unintended modifications. Use with caution.

Post-Processing Hooks

Process the generated schema JSON with an external command:

Flag	Environment Variable	Description
--post-hook-cmd=CMD	-	Command to post-process the generated tool schema JSON

Example:

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

This feature is useful for filtering or transforming the schema before generating documentation or for debugging purposes.