Skip to main content

DIAL MCP Gateway environment variables

This reference lists every environment variable that DIAL MCP Gateway reads, with its default. It is for platform engineers who deploy the gateway and have read the configuration overview. Core-side settings and the router's file are described there.

Source of defaults​

Defaults are checked against the settings model, which reads 56 variables. Names are case-insensitive. The upstream pod contract lists 55 of them; it omits RESOURCE_PATH_MAX_SEGMENTS.

The upstream docker-compose.yml passes each variable explicitly and supplies its own fallbacks. Two differ from the image: ROLES_SOURCE_PATH falls back to roles and IDP_SSO_SESSION_MAX_SECONDS to 86400, while the image has no default for either. Source: Compose file.

Required settings​

VariableDescription
ROLES_SOURCE_PATHThe claim path of the user's roles in the identity provider's token, for example roles or resource_access.<CLIENT>.roles.
IDP_SSO_SESSION_MAX_SECONDSHow long the identity provider keeps the user's refresh token usable, in seconds. An assertion about the provider's session policy that the gateway can't check.
IDP_CLIENT_SECRET or IDP_CLIENT_SECRET_FILEExactly one of them. The gateway's client at the provider is confidential in every mode.
GATEWAY_SIGNING_KEY or GATEWAY_SIGNING_KEYSExactly one of them.
GATEWAY_CUSTODY_KEYSThe key that encrypts the identity provider's refresh token.

The variables in the next table have defaults but describe the deployment, so a real deployment sets them too:

VariableWhy its default doesn't fit
GATEWAY_PUBLIC_ORIGINThe default is http://localhost:8090.
DIAL_CORE_BASE_URLThe default is the upstream Compose service name.
IDP_ISSUERThe default is the reserved domain https://idp.example.com/.
IDP_CLIENT_IDThe default is the repository's example client.
IDP_CLIENT_SCOPESThe default is the upstream Keycloak realm's set.
DCR_ENABLEDOff by default; clients that register dynamically need it on.

Source: the minimal configuration.

Topology and DIAL Core​

VariableDefaultDescription
GATEWAY_PUBLIC_ORIGINhttp://localhost:8090The origin that MCP clients see. It is the iss of every token, the base of every discovery document, and the prefix of the two callback URLs. Must equal the router's $mcp_origin.
GATEWAY_INTERNAL_PORT8091The port the gateway binds on all interfaces, from 1 to 65535. Never publish it outside the pod.
DIAL_CORE_BASE_URLhttp://core:8080DIAL Core as the gateway reaches it. Used for the access check and the credential sign-in.
DIAL_COMPOSE_NETWORKdial-instance_defaultRead by the settings model but used only by the upstream Compose file, as the name of the DIAL network to join. No effect in a cluster.
ROLES_SOURCE_PATH—Required. A dot-separated claim path. When the path is missing from the user's token, issuance fails with an error that names it; an empty value is copied as no roles.
ROLES_CLAIM_NAMErolesThe claim the gateway writes the roles array to. Core's gateway entry reads it through rolePath.

Sources: topology and Core settings and the roles rule.

Identity provider​

VariableDefaultDescription
IDP_ISSUERhttps://idp.example.com/The provider's issuer, matched exactly against every token's iss. Discovery reads <IDP_ISSUER>/.well-known/openid-configuration. Must be HTTPS unless IDP_BACKCHANNEL_BASE_URL is set.
IDP_CLIENT_IDdial-mcp-proxyThe gateway's confidential client at the provider.
IDP_CLIENT_SECRET—The client secret. Required unless IDP_CLIENT_SECRET_FILE is set; setting both stops startup.
IDP_CLIENT_SECRET_FILE—The path of a read-only file that holds the client secret, read once at startup.
IDP_CLIENT_SCOPESprofile,emailComma-separated scopes the gateway requests, and the only ones. A client's own scope parameter is accepted and ignored. Never include offline_access.
IDP_PKCE_ENABLEDtrueWhether the gateway sends a PKCE challenge to the provider. Clients of the gateway always need PKCE.
IDP_BACKCHANNEL_BASE_URL—An origin that replaces the issuer's scheme and host for server-to-server calls: discovery, token, refresh, and JWKS. Point it only at a host that serves the provider alone.
IDP_DISCOVERY_CACHE_TTL_SECONDS300How long a fetched discovery document, or a failure to fetch it, is reused. Nothing is fetched at startup.
IDP_AUTHORIZATION_ENDPOINT—Direct endpoint, set together with the next two. When all three are set, no discovery runs.
IDP_TOKEN_ENDPOINT—Direct endpoint; all three or none.
IDP_JWKS_URI—Direct endpoint; all three or none.
GATEWAY_OUTBOUND_TIMEOUT_SECONDS30.0Timeout of a call to Core or the provider. Long because Core's credential call waits for the toolset's authorization server.

Sources: identity provider settings and the endpoint source.

For a provider whose discovery document is missing or served at another path, set the three direct endpoints and keep IDP_ISSUER as the value to match. Discovery picks up a provider's endpoint changes within the cache TTL; direct endpoints don't change until you update them.

Tokens and refresh​

VariableDefaultDescription
GATEWAY_ACCESS_TOKEN_TTL_SECONDS600Access token lifetime, from 1 to 3600. Access tokens can't be revoked.
GATEWAY_CODE_TTL_SECONDS300Authorization code lifetime, from 1 to 900.
GATEWAY_FLOW_TTL_SECONDS600How long an unfinished browser sign-in stays valid, from 1 to 3600.
GATEWAY_REFRESH_TTL_SECONDS28800Absolute refresh token lifetime. Rotation keeps the original expiry. Must not exceed IDP_SSO_SESSION_MAX_SECONDS.
IDP_SSO_SESSION_MAX_SECONDS—Required. The provider's refresh token lifetime for this client, such as Keycloak's SSO Session Max.
GATEWAY_ROTATE_REFRESH_TOKENStrueIssue a new refresh token on every refresh. Turn it off only when the provider doesn't rotate its own refresh tokens.
GATEWAY_ROTATION_GRACE_SECONDS60How long a rotated refresh token still works for a request that raced the rotation, from 0 to 600.
GATEWAY_INFER_RESOURCE_SINGLE_TOOLSETfalseUse the only toolset when a request has no resource. Needs TOOLSETS with exactly one entry, and never applies to applications.
GATEWAY_AUDIENCE_MARKERdial-mcp-proxyThe value added to every access token's aud. Must equal the audience of Core's gateway entry.

Sources: token settings and refresh, rotation, and revocation.

Each refresh asks the provider for the user's current claims, so role changes reach new access tokens within the access token lifetime. When the provider session ends, refreshes fail with idp_session_ended and the user signs in again.

Warning

With GATEWAY_ROTATE_REFRESH_TOKENS=false on a provider that rotates refresh tokens, every refresh after the first fails and users sign in again.

Resources and clients​

VariableDefaultDescription
TOOLSETS{}JSON object that limits which toolsets are served, keyed by the toolset's path, for example {"notion":{"scopes_supported":["default"]}}. Empty serves every toolset whose path is valid; Core decides whether it exists after sign-in.
APPS{}JSON object that limits which applications are served, keyed by path, for example {"my-app":{}}. Entries take no members. Independent of TOOLSETS.
RESOURCE_PATH_MAX_SEGMENTS32Maximum number of segments in a toolset or application path. The decoded path is also limited to 900 bytes.
PRE_REGISTERED_CLIENTS{}JSON object of clients, keyed by client ID, each with redirect_uris and an optional client_name.
GATEWAY_CIMD_ALLOWED_ORIGINShttps://claude.aiComma-separated origins allowed to host client ID metadata documents. Empty allows none.
GATEWAY_CIMD_USER_AGENTdial-mcp-gateway/0.1 (+mcp-signin)The User-Agent of metadata document fetches. The origin of Claude Code's document rejects library default agents.
GATEWAY_CIMD_CONNECT_TIMEOUT_SECONDS5.0Connect timeout of a metadata document fetch.
GATEWAY_CIMD_TOTAL_TIMEOUT_SECONDS10.0Total timeout of a metadata document fetch.
GATEWAY_CIMD_MAX_DOCUMENT_BYTES65536Maximum size of a metadata document.
GATEWAY_CIMD_CACHE_TTL_SECONDS300How long a fetched metadata document is cached.
GATEWAY_CIMD_CACHE_MAX_ENTRIES256Maximum number of cached metadata documents.

Sources: registration settings and client registration.

The gateway resolves a client in this order: PRE_REGISTERED_CLIENTS, then a client ID metadata document when the ID is an HTTPS URL, then dynamic registration when enabled. A metadata document is fetched over HTTPS only, without redirects, and never from a private, loopback, or link-local address.

A redirect URI must be HTTPS, or HTTP on localhost, 127.0.0.1, or [::1]. A plain HTTP URI on another host is refused at every entry point: a pre-registered entry with one stops startup.

A toolset path is the toolset's ID in Core: a name such as notion, or toolsets/<BUCKET>/<PATH> for a stored toolset. Its first segment must not be authorize, token, register, revoke, callback, consent, or jwks.json. These paths belong to the gateway's own endpoints.

Dynamic client registration​

VariableDefaultDescription
DCR_ENABLEDfalseEnables POST /dial/register and its entry in the authorization server metadata. While off, stored registrations are kept but don't resolve.
DCR_STORE_PATH/data/dcr-registrations.jsonThe registration store, one JSON file. Put it on a persistent volume writable by uid 10001.
DCR_MAX_REGISTRATIONS1024Maximum number of stored registrations. New ones are refused at the limit; nothing is evicted and nothing expires.
DCR_MAX_BODY_BYTES8192Maximum registration request size. The three limits below must fit inside it, or startup stops.
DCR_MAX_REDIRECT_URIS8Maximum redirect URIs in one registration.
DCR_MAX_REDIRECT_URI_LENGTH512Maximum length of one redirect URI.
DCR_MAX_CLIENT_NAME_LENGTH256Maximum length of client_name.

Sources: registration settings and the store.

The store is written before each registration is confirmed, by atomic replace. An unreadable store stops startup. To recover, rename the file and restart; clients then register again on their next sign-in. Losing the store costs each client one registration and invalidates no issued token.

Limits and audit​

VariableDefaultDescription
GATEWAY_RATE_PER_SOURCE_PER_MINUTE30Requests per minute from one source address, read from the router's X-Real-IP header.
GATEWAY_RATE_GLOBAL_PER_MINUTE600Requests per minute in total.
GATEWAY_FLOWS_MAX_LIVE10000Maximum unfinished sign-ins. The oldest are dropped first, and their users see a session-expired page.
GATEWAY_APPROVED_CLIENTS_MAX10000Maximum remembered client approvals. The oldest are dropped first, and their users see the approval page again.
GATEWAY_FORM_MAX_BODY_BYTES16384Maximum request size at /dial/token and /dial/revoke.
GATEWAY_CIMD_MAX_CONCURRENT_FETCHES8Maximum metadata document fetches at one time.
AUDIT_FACT_MAX_LENGTH256Maximum length of a request value in an audit record. Longer values are truncated.

Sources: limit settings and abuse bounds.

One limiter, counted per one-minute window, covers the sign-in, callback, approval, protected-resource, registration, token, and revocation endpoints together. The authorization server metadata, the JWKS, and /healthz are not limited.

Keys and secrets​

VariableDefaultDescription
GATEWAY_SIGNING_KEY—An unencrypted RSA private key in PEM form, at least 2048 bits. Escaped \n line breaks are accepted. Tokens are signed with RS256.
GATEWAY_SIGNING_KEYS{}The signing keyset, for rotation. Can't be combined with GATEWAY_SIGNING_KEY.
GATEWAY_CUSTODY_KEYS{}Required. 32-byte AES-256-GCM keys in base64, which encrypt the identity provider's refresh token inside the gateway's refresh token.
GATEWAY_CUSTODY_PROVIDER_TOKEN_MAX_BYTES4096Maximum size of the provider's refresh token. A larger one fails the sign-in. Must leave room inside GATEWAY_FORM_MAX_BODY_BYTES, or startup stops.

Sources: secret settings and Secrets.

GATEWAY_CUSTODY_KEYS takes one key in the flat form, which can't be rotated:

GATEWAY_CUSTODY_KEYS='{"k-2026-11":"<BASE64_32_BYTE_KEY>"}'

Both keysets also take a structured form. Each entry names where its key is, through source and ref, and its role. Exactly one entry is active; retained entries only verify or decrypt. The keyset holds no key material itself.

GATEWAY_SIGNING_KEYS='{"s-2026-11":{"source":"file","ref":"/run/secrets/signing-2026-11.pem","role":"active"},"s-2026-05":{"source":"env","ref":"SIGNING_KEY_2026_05","role":"retained"}}'
SIGNING_KEY_2026_05=<PEM_WITH_ESCAPED_NEWLINES>

A source of env reads the variable that ref names; file reads the file at ref, mounted read-only. The source kms is reserved and stops startup. Two entries with the same key, which share a kid, also stop startup.

Key rotation​

The kid of a signing key is a hash of its public key. A retained signing key stays in the JWKS, so Core keeps accepting tokens it signed. Rotate the signing key in these steps:

  1. Publish. Add the new key as retained and restart.
  2. Wait. Wait at least the positiveCacheExpirationMs of Core's gateway entry, default 10 minutes.
  3. Promote. Make the new key active and the old one retained, then restart.
  4. Drain. Wait for the old key's tokens to expire, at most GATEWAY_REFRESH_TTL_SECONDS.
  5. Remove. Delete the old entry and restart.

A custody key isn't published, so its rotation is one step: add the new key as active and keep the old one as retained. New refresh tokens are encrypted with the active key, and retained keys still decrypt older ones until you remove them. Removing a retained entry at any time cuts off every token that depends on it, which is the response to a leaked key. Source: Key rotation.

A variable named in a ref must also reach the container. The upstream Compose file passes a fixed list of variables, so add the new name to it.

Startup checks​

The gateway refuses to start, and names the setting, when:

  • a required setting is missing, or both spellings of the client secret or the signing key are set;
  • GATEWAY_REFRESH_TTL_SECONDS exceeds IDP_SSO_SESSION_MAX_SECONDS;
  • the signing key is missing, unreadable, not RSA, smaller than 2048 bits, or still the .env.example placeholder;
  • a keyset has no active entry, more than one active entry, a custody key that is not 32 bytes, or a kms source;
  • TOOLSETS, APPS, or PRE_REGISTERED_CLIENTS is not a JSON object, has a member the gateway doesn't know, or names a path that can't be routed;
  • a TOOLSETS entry still has the removed authentication_type member;
  • GATEWAY_INFER_RESOURCE_SINGLE_TOOLSET is on without exactly one TOOLSETS entry;
  • a pre-registered client has a plain HTTP redirect URI on a host other than loopback;
  • the direct identity provider endpoints are partly set, malformed, or plain HTTP without IDP_BACKCHANNEL_BASE_URL, or IDP_ISSUER is plain HTTP without it;
  • a size limit doesn't fit inside its request limit;
  • the dynamic client registration store can't be read, or holds a plain HTTP redirect URI on a host other than loopback.

Source: Startup refusals.

Further reading​