Skip to main content

DIAL OpenAPI to MCP environment variables

The OpenAPI to MCP bridge reads all of its settings from environment variables. This reference lists every one of them, with its default and behavior. It is for platform engineers who deploy the bridge. For the application type and application properties, see Configuration.

Version scope​

Defaults below are checked against 0.2.1: server.py, cache.py, telemetry.py, __main__.py, and the Dockerfile. The upstream CONFIGURATION.md describes the header lists as limits on the headers clients forward. In the code, they apply only to extra_headers entries and to the header of a DIAL credential.

The development branch adds PATH_PARAMS_ALLOW_RESERVED and MCP_VALIDATE_OUTPUT. No release has them yet.

The bridge also loads a .env file from its working directory at startup. A variable already set in the environment takes precedence over the file.

Server​

VariableDefaultDescription
MCP_PORT8080The port of /mcp, the schema endpoint, /health, and /ready. The server listens on all interfaces.
LOG_LEVELINFOThe Python log level. An unknown name falls back to INFO.

The image's own Docker health check calls http://localhost:8080/health. If you change MCP_PORT, configure the platform's probes on the new port.

Cache​

VariableDefaultDescription
MCP_CACHE_MAX_SIZE100The most cache entries kept. When the cache is full, the least recently used one is removed. 0 removes the limit.
MCP_CACHE_TTL3600The seconds an unused cache entry is kept. 0 keeps cache entries until the size limit removes them.
MCP_CACHE_CLEANUP_INTERVAL300The seconds between sweeps that remove expired cache entries. 0 turns the sweep off; an expired cache entry is still rebuilt when it is next requested.

The bridge keeps one cache entry per document and base URL, keyed by a SHA-256 hash of both. Each cache entry holds the tools built from the document and the HTTP client for its API. Cached entries hold no forwarded headers and no credentials. The cache belongs to one process, so each replica builds its own. A negative or non-integer value stops the bridge at startup.

Outbound headers​

VariableDefaultDescription
OUTBOUND_HEADER_ALLOWLISTUnsetComma-separated header names. When unset, any name that isn't blocked is allowed. When set but empty, no name is allowed. When it lists names, only those are allowed.
OUTBOUND_HEADER_BLOCKLISTThe default list belowComma-separated header names that are never allowed. Setting it replaces the default list, and setting it empty blocks nothing.

The default block list is authorization, cookie, set-cookie, proxy-authorization, host, connection, keep-alive, proxy-authenticate, te, trailer, transfer-encoding, upgrade, forwarded, x-forwarded-for, x-forwarded-host, and x-forwarded-proto. Names match case-insensitively, and the block list wins over the allowlist.

The lists check each extra_headers entry, whether it comes from an application property, the MCP message, or the X-EXTRA-HEADERS header. A rejected entry fails the tool listing or the tool call. In 0.2.1, the block list also checks the header of a DIAL credential. The lists don't apply to the headers the bridge copies from the incoming request; see Secure the bridge.

DIAL credentials​

VariableDefaultDescription
DIAL_URL—The DIAL Core URL. The bridge needs it only for applications that set external_service.
DIAL_CORE_URL—Used when DIAL_URL is unset or empty

Without either variable, a tool call of an application with external_service fails with 500. See Credentials from external services.

Observability​

VariableDefaultDescription
OTEL_TRACES_EXPORTERUnsetotlp exports traces.
OTEL_METRICS_EXPORTERUnsetComma-separated. otlp pushes metrics to the collector, and prometheus serves them on port 9464.
OTEL_LOGS_EXPORTERUnsetotlp also exports the bridge's log records. Console logging continues.
OTEL_EXPORTER_OTLP_ENDPOINTUnsetThe collector endpoint, passed to each OTLP exporter
OTEL_EXPORTER_OTLP_PROTOCOLgrpchttp/protobuf or http/json select the OTLP/HTTP exporters. Any other value selects gRPC.
OTEL_SERVICE_NAMEopenapi-to-mcpThe service name on all signals
OTEL_RESOURCE_ATTRIBUTESUnsetComma-separated key=value pairs added to the resource

With none of the three exporter variables set, telemetry is off and no port is opened. The bridge sets telemetry up when it starts. If setup fails, it logs the error and runs without telemetry.

Further reading​