Skip to main content

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​

PlaceWhat it setsReference
Gateway environment variablesPublic origin, Core address, identity provider, keys, token lifetimes, client registration, and limitsEnvironment variables
router/nginx.confCore's address, the origin quoted in challenges, and the routing mapFront router
Identity providerThe gateway's confidential client, its redirect URI, scopes, and claimsRegister the identity provider client
DIAL Core static settingsAn identity provider entry for the gateway, the trusted authorization server, and the allowed redirect URIsConfigure 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.

  1. 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>"
    }
    }
    }
    MemberRule
    jwksUrlThe gateway's /dial/jwks.json on port 8091, as Core reaches it inside the cluster.
    issuerPatternA regular expression that fully matches GATEWAY_PUBLIC_ORIGIN, the iss of every gateway token.
    rolePathEqual to the gateway's ROLES_CLAIM_NAME, default roles.
    projectPathThe claim that carries the project in the identity provider's tokens; the gateway copies it unchanged.
    audienceEqual to GATEWAY_AUDIENCE_MARKER, default dial-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 issuerPattern matches the token's iss, and an entry without a pattern never matches. Give every entry an issuerPattern, 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 issuerPattern must match IDP_ISSUER, and a configured audience must match those tokens' aud.

  2. 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 authorizationServers is set, and that metadata names the gateway. Sources: setting read and disabled check.

    allowedRedirectUris lists 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's redirect_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.

  3. 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 OAUTH toolsets 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.

  4. 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 to https://mcp.example.com/dial/<TOOLSET>/mcp without a token returns 401 with a WWW-Authenticate header 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.

PropertyValue
Client typeConfidential, authorization code flow only. The secret goes to IDP_CLIENT_SECRET or IDP_CLIENT_SECRET_FILE.
PKCES256. 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
ScopesThe values of IDP_CLIENT_SCOPES, and nothing more. Never offline_access. Add openid where the provider needs it to issue an ID token.
Claimssub, the roles at ROLES_SOURCE_PATH, and every claim Core's rules use, such as the project claim.
Session lengthThe 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.

LineReleased valueSet it to
upstream coreserver core:8080;DIAL Core's address inside the cluster
$mcp_originhttp://localhost:8090The 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 8091 stays inside. Core must reach it for the JWKS, but hosts and the ingress must not. The gateway's per-source rate limit trusts the X-Real-IP header that the router sets.
  • TLS at the ingress. The router listens on 8090 over 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, the RuntimeDefault seccomp 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 of DCR_STORE_PATH, with fsGroup 10001. 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 returns 413. 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:

ResourceURL
Toolset defined in Core's configurationhttps://mcp.example.com/dial/<TOOLSET>/mcp
Toolset stored in a buckethttps://mcp.example.com/dial/toolsets/<BUCKET>/<PATH>/mcp
Application with an MCP endpointhttps://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, default https://claude.ai. The repository records Claude Code signing in this way.
  • Dynamic client registration. Set DCR_ENABLED=true and 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​

SymptomWhat to check
The container exits at startupThe log names the refused setting. See Startup checks.
The client reports a discovery or authorization errorThe 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 configurationCore 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 accessThe toolset's userRoles or the application's access settings exclude the user's roles.
The sign-in page says the resource is not registeredThe toolset or application ID in the URL.
The sign-in page says the credential is configured in DIAL directlyThe 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 stepallowedRedirectUris carries <GATEWAY_PUBLIC_ORIGIN>/dial/callback/upstream, and the toolset was repaired after the change.
Tool calls return 401 after sign-inThe gateway entry in Core: issuerPattern, jwksUrl reachable from Core, and audience equal to GATEWAY_AUDIENCE_MARKER.
Tool calls return 403 after sign-inrolePath equals ROLES_CLAIM_NAME. Core rules that use scope, acr, or another claim the gateway drops never match.
Every refresh after the first failsThe provider rotates refresh tokens while GATEWAY_ROTATE_REFRESH_TOKENS=false.
Bursts of idp_session_ended in the audit logIDP_SSO_SESSION_MAX_SECONDS is longer than the provider's real session lifetime.
Dynamically registered clients fail after a restartThe registration store is not on a persistent volume.