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
| Variable | Description |
|---|---|
ROLES_SOURCE_PATH | The 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_SECONDS | How 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_FILE | Exactly one of them. The gateway's client at the provider is confidential in every mode. |
GATEWAY_SIGNING_KEY or GATEWAY_SIGNING_KEYS | Exactly one of them. |
GATEWAY_CUSTODY_KEYS | The 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:
| Variable | Why its default doesn't fit |
|---|---|
GATEWAY_PUBLIC_ORIGIN | The default is http://localhost:8090. |
DIAL_CORE_BASE_URL | The default is the upstream Compose service name. |
IDP_ISSUER | The default is the reserved domain https://idp.example.com/. |
IDP_CLIENT_ID | The default is the repository's example client. |
IDP_CLIENT_SCOPES | The default is the upstream Keycloak realm's set. |
DCR_ENABLED | Off by default; clients that register dynamically need it on. |
Source: the minimal configuration.
Topology and DIAL Core
| Variable | Default | Description |
|---|---|---|
GATEWAY_PUBLIC_ORIGIN | http://localhost:8090 | The 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_PORT | 8091 | The port the gateway binds on all interfaces, from 1 to 65535. Never publish it outside the pod. |
DIAL_CORE_BASE_URL | http://core:8080 | DIAL Core as the gateway reaches it. Used for the access check and the credential sign-in. |
DIAL_COMPOSE_NETWORK | dial-instance_default | Read 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_NAME | roles | The 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
| Variable | Default | Description |
|---|---|---|
IDP_ISSUER | https://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_ID | dial-mcp-proxy | The 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_SCOPES | profile,email | Comma-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_ENABLED | true | Whether 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_SECONDS | 300 | How 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_SECONDS | 30.0 | Timeout 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
| Variable | Default | Description |
|---|---|---|
GATEWAY_ACCESS_TOKEN_TTL_SECONDS | 600 | Access token lifetime, from 1 to 3600. Access tokens can't be revoked. |
GATEWAY_CODE_TTL_SECONDS | 300 | Authorization code lifetime, from 1 to 900. |
GATEWAY_FLOW_TTL_SECONDS | 600 | How long an unfinished browser sign-in stays valid, from 1 to 3600. |
GATEWAY_REFRESH_TTL_SECONDS | 28800 | Absolute 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_TOKENS | true | Issue a new refresh token on every refresh. Turn it off only when the provider doesn't rotate its own refresh tokens. |
GATEWAY_ROTATION_GRACE_SECONDS | 60 | How long a rotated refresh token still works for a request that raced the rotation, from 0 to 600. |
GATEWAY_INFER_RESOURCE_SINGLE_TOOLSET | false | Use the only toolset when a request has no resource. Needs TOOLSETS with exactly one entry, and never applies to applications. |
GATEWAY_AUDIENCE_MARKER | dial-mcp-proxy | The 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=falseon a provider that rotates refresh tokens, every refresh after the first fails and users sign in again.
Resources and clients
| Variable | Default | Description |
|---|---|---|
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_SEGMENTS | 32 | Maximum 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_ORIGINS | https://claude.ai | Comma-separated origins allowed to host client ID metadata documents. Empty allows none. |
GATEWAY_CIMD_USER_AGENT | dial-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_SECONDS | 5.0 | Connect timeout of a metadata document fetch. |
GATEWAY_CIMD_TOTAL_TIMEOUT_SECONDS | 10.0 | Total timeout of a metadata document fetch. |
GATEWAY_CIMD_MAX_DOCUMENT_BYTES | 65536 | Maximum size of a metadata document. |
GATEWAY_CIMD_CACHE_TTL_SECONDS | 300 | How long a fetched metadata document is cached. |
GATEWAY_CIMD_CACHE_MAX_ENTRIES | 256 | Maximum 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
| Variable | Default | Description |
|---|---|---|
DCR_ENABLED | false | Enables 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.json | The registration store, one JSON file. Put it on a persistent volume writable by uid 10001. |
DCR_MAX_REGISTRATIONS | 1024 | Maximum number of stored registrations. New ones are refused at the limit; nothing is evicted and nothing expires. |
DCR_MAX_BODY_BYTES | 8192 | Maximum registration request size. The three limits below must fit inside it, or startup stops. |
DCR_MAX_REDIRECT_URIS | 8 | Maximum redirect URIs in one registration. |
DCR_MAX_REDIRECT_URI_LENGTH | 512 | Maximum length of one redirect URI. |
DCR_MAX_CLIENT_NAME_LENGTH | 256 | Maximum 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
| Variable | Default | Description |
|---|---|---|
GATEWAY_RATE_PER_SOURCE_PER_MINUTE | 30 | Requests per minute from one source address, read from the router's X-Real-IP header. |
GATEWAY_RATE_GLOBAL_PER_MINUTE | 600 | Requests per minute in total. |
GATEWAY_FLOWS_MAX_LIVE | 10000 | Maximum unfinished sign-ins. The oldest are dropped first, and their users see a session-expired page. |
GATEWAY_APPROVED_CLIENTS_MAX | 10000 | Maximum remembered client approvals. The oldest are dropped first, and their users see the approval page again. |
GATEWAY_FORM_MAX_BODY_BYTES | 16384 | Maximum request size at /dial/token and /dial/revoke. |
GATEWAY_CIMD_MAX_CONCURRENT_FETCHES | 8 | Maximum metadata document fetches at one time. |
AUDIT_FACT_MAX_LENGTH | 256 | Maximum 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
| Variable | Default | Description |
|---|---|---|
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_BYTES | 4096 | Maximum 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:
- Publish. Add the new key as
retainedand restart. - Wait. Wait at least the
positiveCacheExpirationMsof Core's gateway entry, default 10 minutes. - Promote. Make the new key
activeand the old oneretained, then restart. - Drain. Wait for the old key's tokens to expire, at most
GATEWAY_REFRESH_TTL_SECONDS. - 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_SECONDSexceedsIDP_SSO_SESSION_MAX_SECONDS;- the signing key is missing, unreadable, not RSA, smaller than 2048 bits, or still the
.env.exampleplaceholder; - a keyset has no active entry, more than one active entry, a custody key that is not 32 bytes, or a
kmssource; TOOLSETS,APPS, orPRE_REGISTERED_CLIENTSis not a JSON object, has a member the gateway doesn't know, or names a path that can't be routed;- a
TOOLSETSentry still has the removedauthentication_typemember; GATEWAY_INFER_RESOURCE_SINGLE_TOOLSETis on without exactly oneTOOLSETSentry;- 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, orIDP_ISSUERis 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
- Endpoints and sign-in flow — the gateway's endpoints, tokens, and audit events
- Identity providers — the Core entry that verifies the gateway's tokens
- Toolsets security — the authorization server and redirect URI settings in Core
- Toolsets — toolset authentication types and credential sign-in