DIAL MCP Gateway configuration
DIAL MCP Gateway is configured in four places: its own environment, the front router's configuration file, a client at the identity provider, and DIAL Core's static settings. This page shows what goes where, how to connect the gateway to Core, and how to diagnose a failed sign-in. It is for platform engineers who know the gateway's role and Core's static settings.
Where each setting lives
| Place | What it sets | Reference |
|---|---|---|
| Gateway environment variables | Public origin, Core address, identity provider, keys, token lifetimes, client registration, and limits | Environment variables |
router/nginx.conf | Core's address, the origin quoted in challenges, and the routing map | Front router |
| Identity provider | The gateway's confidential client, its redirect URI, scopes, and claims | Register the identity provider client |
| DIAL Core static settings | An identity provider entry for the gateway, the trusted authorization server, and the allowed redirect URIs | Configure DIAL Core |
The gateway reads environment variables only, plus a .env file in its working directory when one exists. Values that a startup check refuses stop the container with a message that names the setting. Source: settings model.
Configure DIAL Core
Core needs three changes. The examples use https://mcp.example.com as the gateway's public origin and the upstream Compose service name mcp-signin-gateway.
-
Trust the gateway's tokens. Add an identity provider entry for the gateway next to the existing one:
{
"identityProviders": {
"dial-mcp-proxy": {
"jwksUrl": "http://mcp-signin-gateway:8091/dial/jwks.json",
"issuerPattern": "https://mcp\\.example\\.com",
"rolePath": "roles",
"projectPath": "<PROJECT_CLAIM_PATH>",
"audience": "dial-mcp-proxy",
"loggingKey": "<SAME_AS_PRIMARY_ENTRY>",
"loggingSalt": "<SAME_AS_PRIMARY_ENTRY>"
},
"keycloak": {
"jwksUrl": "https://<IDP_HOST>/realms/<REALM>/protocol/openid-connect/certs",
"issuerPattern": "https://<IDP_HOST>/realms/<REALM>",
"rolePath": "<ROLES_CLAIM_PATH>"
}
}
}Member Rule jwksUrlThe gateway's /dial/jwks.jsonon port8091, as Core reaches it inside the cluster.issuerPatternA regular expression that fully matches GATEWAY_PUBLIC_ORIGIN, theissof every gateway token.rolePathEqual to the gateway's ROLES_CLAIM_NAME, defaultroles.projectPathThe claim that carries the project in the identity provider's tokens; the gateway copies it unchanged. audienceEqual to GATEWAY_AUDIENCE_MARKER, defaultdial-mcp-proxy. Core checks this value only, not the per-resource audience.loggingKey,loggingSaltThe same values as the primary entry, so gateway traffic is attributed and hashed like other traffic. With more than one entry, Core picks the entry whose
issuerPatternmatches the token'siss, and an entry without a pattern never matches. Give every entry anissuerPattern, including the existing one. See Several providers, the provider selection, and the issuer match.The gateway also calls Core with the identity provider's own token for the user. The existing entry must accept tokens issued to the gateway's client: its
issuerPatternmust matchIDP_ISSUER, and a configuredaudiencemust match those tokens'aud. -
Name the gateway as the authorization server, and allow its callback. Set
toolsets.security:{
"toolsets": {
"security": {
"authorizationServers": ["https://mcp.example.com"],
"allowedRedirectUris": [
"https://mcp.example.com/dial/callback/upstream",
"https://chat.example.com/auth/toolset-signin",
"https://admin.example.com/toolset-signin"
]
}
}
}Core publishes protected-resource metadata only when
authorizationServersis set, and that metadata names the gateway. Sources: setting read and disabled check.allowedRedirectUrislists the gateway's upstream callback first, then the DIAL Chat and DIAL Admin callbacks. When Core registers a toolset's OAuth client dynamically, it registers every URI in the list and stores the first one the upstream returns as the toolset'sredirect_uri. The order comes from the gateway's runbook. The Chat and Admin paths come from DIAL Chat's routes and DIAL Admin's sign-in buttons. -
Register the callback with existing toolsets. A toolset whose client was registered dynamically before the callback was in the list doesn't accept it. Re-run the registration:
curl -X POST 'https://<DIAL_HOST>/v1/ops/toolset/<BUCKET>/<PATH>/repair' \
-H 'Authorization: Bearer <TOKEN_WITH_WRITE_ACCESS>'The repair applies only to
OAUTHtoolsets with a dynamically registered client, and needs write access to the toolset. For a client registered by hand, add the callback in the upstream provider's console instead. Source: ToolSetRepairService.Warning
A repair issues a new client ID and deletes every credential stored for the toolset. Every user of that toolset signs in again.
-
Check the result. Fetch
https://mcp.example.com/.well-known/oauth-protected-resource/dial/<TOOLSET>/mcp; it names the gateway as the authorization server. An MCP request tohttps://mcp.example.com/dial/<TOOLSET>/mcpwithout a token returns401with aWWW-Authenticateheader that quotes that document.
Core caches each gateway key for the entry's positiveCacheExpirationMs, default 600000 (10 minutes). That window sets how long key rotation waits before a new key signs. Source: IdentityProvider.
Register the identity provider client
Register a client for the gateway at the identity provider that DIAL Core already trusts for users.
| Property | Value |
|---|---|
| Client type | Confidential, authorization code flow only. The secret goes to IDP_CLIENT_SECRET or IDP_CLIENT_SECRET_FILE. |
| PKCE | S256. Turn the gateway's IDP_PKCE_ENABLED off only for a provider that can't support PKCE. |
| Redirect URI | <GATEWAY_PUBLIC_ORIGIN>/dial/callback/idp |
| Scopes | The values of IDP_CLIENT_SCOPES, and nothing more. Never offline_access. Add openid where the provider needs it to issue an ID token. |
| Claims | sub, the roles at ROLES_SOURCE_PATH, and every claim Core's rules use, such as the project claim. |
| Session length | The provider's refresh token lifetime for this client goes to IDP_SSO_SESSION_MAX_SECONDS. On Keycloak, this is the realm's SSO Session Max. |
The gateway copies the provider's token claims into its own token. A missing roles claim stops issuance with an error that names ROLES_SOURCE_PATH. For Keycloak, the repository's provision_keycloak.py creates such a client. It also recommends enabling the realm's refresh token revocation, revokeRefreshToken, when internal connections are plain HTTP.
Front router
The router is stock nginx running router/nginx.conf from the release tag. The file is part of the component's contract, so keep its routing as released. Two of its values describe the deployment and must change.
| Line | Released value | Set it to |
|---|---|---|
upstream core | server core:8080; | DIAL Core's address inside the cluster |
$mcp_origin | http://localhost:8090 | The exact value of GATEWAY_PUBLIC_ORIGIN |
The pod has these requirements, from the pod contract:
- One pod, one replica. The router and the gateway share a network namespace, and the router reaches the gateway at
127.0.0.1:8091. Sign-in state is in memory, so a second replica breaks sign-ins. - Port
8091stays inside. Core must reach it for the JWKS, but hosts and the ingress must not. The gateway's per-source rate limit trusts theX-Real-IPheader that the router sets. - TLS at the ingress. The router listens on
8090over plain HTTP; the cluster ingress terminates TLS for the public origin. - Security context. Run as non-root user and group
10001, with no privilege escalation, all capabilities dropped, theRuntimeDefaultseccomp profile, and a read-only root file system. The router needs writable temporary and log paths. - Volumes. When
DCR_ENABLED=true, mount a persistent, writable volume at the directory ofDCR_STORE_PATH, withfsGroup10001. Mount secret files read-only.
Note
The router caps every request body at 16,384 bytes (
client_max_body_size), MCP requests included. A larger MCP request through the gateway's origin returns413. Source: nginx.conf.
Example: Docker Compose
This fragment adds the gateway and its router to an existing DIAL Compose project whose Core service is core. It follows the upstream Compose file but uses the released image. Set <VERSION> to a release tag, and place router/nginx.conf from that tag next to it, edited as in Front router.
services:
mcp-signin-gateway:
image: epam/ai-dial-mcp-gateway:<VERSION>
ports:
- "8090:8090" # the router's port; the router joins this service's network namespace
environment:
GATEWAY_PUBLIC_ORIGIN: https://mcp.example.com
DIAL_CORE_BASE_URL: http://core:8080
IDP_ISSUER: https://<IDP_HOST>/realms/<REALM>
IDP_CLIENT_ID: dial-mcp-proxy
IDP_CLIENT_SECRET: ${IDP_CLIENT_SECRET}
IDP_CLIENT_SCOPES: profile,email
ROLES_SOURCE_PATH: <ROLES_CLAIM_PATH>
IDP_SSO_SESSION_MAX_SECONDS: "<PROVIDER_SESSION_SECONDS>" # at least GATEWAY_REFRESH_TTL_SECONDS, 28800
GATEWAY_SIGNING_KEY: ${GATEWAY_SIGNING_KEY}
GATEWAY_CUSTODY_KEYS: ${GATEWAY_CUSTODY_KEYS}
DCR_ENABLED: "true"
volumes:
- ./data:/data # the registration store; writable by uid 10001
restart: unless-stopped
mcp-signin-router:
image: nginx:1.27-alpine
network_mode: "service:mcp-signin-gateway"
volumes:
- ./router/nginx.conf:/etc/nginx/nginx.conf:ro
depends_on:
- mcp-signin-gateway
restart: unless-stopped
Generate the two keys and put them in the project's .env. The signing key may use escaped \n line breaks in an environment variable.
openssl genrsa -out gateway-signing-key.pem 2048
openssl rand -base64 32 # the custody key: GATEWAY_CUSTODY_KEYS='{"k-2026-11":"<BASE64_KEY>"}'
Recreate the pair together, with docker compose up -d --force-recreate. Restarting one service alone splits the shared network namespace, and the router loses the gateway. Source: pod contract, section 8.4.
Connect an MCP client
Give the MCP client a URL on the gateway's origin, never Core's own URL:
| Resource | URL |
|---|---|
| Toolset defined in Core's configuration | https://mcp.example.com/dial/<TOOLSET>/mcp |
| Toolset stored in a bucket | https://mcp.example.com/dial/toolsets/<BUCKET>/<PATH>/mcp |
| Application with an MCP endpoint | https://mcp.example.com/apps/<APPLICATION>/mcp |
The client finds the gateway from the 401 challenge and signs the user in through the browser. For Claude Code:
claude mcp add --transport http notion https://mcp.example.com/dial/notion/mcp
How the gateway identifies the client depends on what the client supports:
- Client ID metadata document. The client's ID is an HTTPS URL. Its origin must be in
GATEWAY_CIMD_ALLOWED_ORIGINS, defaulthttps://claude.ai. The repository records Claude Code signing in this way. - Dynamic client registration. Set
DCR_ENABLED=trueand mount the store. The repository records Cursor signing in this way. - Pre-registered. List the client ID and its redirect URIs in
PRE_REGISTERED_CLIENTS.
The first sign-in of each client for each user stops at an approval page that names the client, the resource, and the redirect URI. A gateway restart forgets approvals, so users approve each client once more.
Troubleshooting
| Symptom | What to check |
|---|---|
| The container exits at startup | The log names the refused setting. See Startup checks. |
| The client reports a discovery or authorization error | The client uses the gateway's origin, and $mcp_origin in the router equals GATEWAY_PUBLIC_ORIGIN. |
| The sign-in page says an administrator must check Core's trust configuration | Core answered 401 to the identity provider's token. Check the existing entry's issuerPattern against IDP_ISSUER, its JWKS reachability, and its audience. |
| The sign-in page says the user has no access | The toolset's userRoles or the application's access settings exclude the user's roles. |
| The sign-in page says the resource is not registered | The toolset or application ID in the URL. |
| The sign-in page says the credential is configured in DIAL directly | The toolset is not OAUTH and has no stored credential at user or global level. |
| The toolset's authorization server rejects the redirect URI, or the sign-in fails at the credential step | allowedRedirectUris carries <GATEWAY_PUBLIC_ORIGIN>/dial/callback/upstream, and the toolset was repaired after the change. |
Tool calls return 401 after sign-in | The gateway entry in Core: issuerPattern, jwksUrl reachable from Core, and audience equal to GATEWAY_AUDIENCE_MARKER. |
Tool calls return 403 after sign-in | rolePath equals ROLES_CLAIM_NAME. Core rules that use scope, acr, or another claim the gateway drops never match. |
| Every refresh after the first fails | The provider rotates refresh tokens while GATEWAY_ROTATE_REFRESH_TOKENS=false. |
Bursts of idp_session_ended in the audit log | IDP_SSO_SESSION_MAX_SECONDS is longer than the provider's real session lifetime. |
| Dynamically registered clients fail after a restart | The registration store is not on a persistent volume. |