Skip to main content

DIAL MCP Gateway

DIAL MCP Gateway is an OAuth 2.0 authorization server that lets MCP clients outside DIAL Chat, such as Claude Code and Cursor, sign in to DIAL toolsets. It signs the user in at the deployment's identity provider, runs the toolset's own OAuth consent, and issues the client a token that DIAL Core accepts. This reference is for platform engineers who run DIAL Core with toolsets.

What the gateway solves​

A toolset that signs in with OAuth needs an upstream credential for each user, for example a Notion token. DIAL Core stores that credential per user, injects it on every tool call, and never returns it to the client. The client holds only a DIAL token.

Users normally create the upstream credential through the sign-in buttons in DIAL Chat or DIAL Admin. An MCP client has no such screen, and a deployment that uses Core only as a model and MCP gateway may not run DIAL Chat at all. The gateway gives MCP clients a standard OAuth sign-in instead. Sources: README and handoff brief.

The gateway also shields MCP clients from identity providers that don't support the MCP authorization specification. A provider without client ID metadata documents or dynamic client registration never faces the client; the gateway is the authorization server the client sees.

How it relates to DIAL Core toolsets​

The gateway decides nothing about access and stores no upstream credential. It reads the toolset from Core as the signed-in user, and Core answers with the toolset's OAuth settings and that user's sign-in status. What happens next depends on that answer.

Toolset state in CoreWhat the gateway does
The user is denied by the toolset's userRolesStops with a no-access page. Core answers 403, the same decision it makes on every tool call.
The user holds a credential at user level, or the toolset has a global credentialSkips the upstream consent and issues the token. Works for every authentication type.
OAUTH with no stored credentialSends the browser to the toolset's authorization server with Core's client ID and PKCE challenge, then passes the returned code to POST /v1/ops/toolset/signin at USER level. Core exchanges the code and stores the credential.
Any type other than OAUTH, such as API_KEY, with no stored credentialStops with a page that says the credential is configured in DIAL directly. The same sign-in succeeds once a credential is stored at user or global level.
Unknown toolsetStops with a not-registered page. Core answers 404.

The code exchange happens inside Core, which holds the client secret and the PKCE verifier. The gateway never sees the upstream token. See the branch logic, the flow description, and the sign-in request.

The gateway serves DIAL applications with an MCP endpoint as well. An application has no upstream credential, so its sign-in is the identity provider sign-in plus Core's access check. In both cases the token carries the user's own identity claims, so Core applies the same roles and finds the same stored credentials as for that user's other DIAL clients.

How the gateway fits together​

The front router and the gateway run in one pod and publish one origin. The router sends the OAuth endpoints to the gateway and MCP traffic straight to DIAL Core, so the gateway is not on the data path. See Endpoints and sign-in flow for the full map.

  1. The client is challenged. An MCP request without a token reaches Core, which answers 401. The router replaces Core's WWW-Authenticate header with one that points to the gateway's protected-resource document.
  2. The client registers and starts OAuth. The client is pre-registered, presents a client ID metadata document, or registers dynamically when DCR_ENABLED=true. It then starts the authorization code flow with PKCE S256 and a resource parameter that names the toolset.
  3. The gateway runs the sign-in. The user signs in at the identity provider, Core checks access, and the user approves the client on first use. When Core holds no credential for an OAUTH toolset, the upstream consent runs and Core stores the result.
  4. The gateway issues tokens. The access token is an RS256 JWT that copies the user's identity claims, signed with the gateway's key. The refresh token carries the identity provider's refresh token, encrypted.
  5. Core serves the tool calls. Core verifies the token against the gateway's JWKS through an extra identity provider entry, then injects the user's stored credential on each call.

Dependencies​

DependencyPurpose
DIAL CoreServes the MCP requests, checks access, stores and injects toolset credentials, and verifies the gateway's tokens. Needs an identity provider entry for the gateway and toolsets.security settings; see Configure DIAL Core.
OpenID Connect identity providerThe provider DIAL Core already trusts for users. The gateway signs users in through its own confidential client there. Keycloak and Entra B2C are the providers the repository records as tested.
Front routernginx 1.27-alpine running the repository's router/nginx.conf, in the same pod as the gateway.
Persistent volumeHolds the dynamic client registration store. Needed only when DCR_ENABLED=true.
Toolset authorization serversThe OAuth servers of the toolsets' MCP servers. The user's browser reaches them during consent.

Deployment​

ItemValue
Imageepam/ai-dial-mcp-gateway, Python 3.12 on Alpine, user and group 10001, linux/amd64 only
Router imagenginx:1.27-alpine with router/nginx.conf from the same release tag as the gateway image, mounted read-only
Ports8090 on the router, the single public port. 8091 on the gateway, reachable by Core for the JWKS and never exposed outside the pod.
LivenessGET /healthz returns {"status": "ok"}. It doesn't check Core or the identity provider; there is no readiness endpoint.
StateSign-in flows, codes, client approvals, and revoked tokens are in memory. The dynamic client registration store is the only file.
ReplicasOne. The gateway is not horizontally scalable.
HelmNot part of the dial chart. The repository defines a pod contract, not a chart.
LogsStandard output. Audit events are JSON lines on the gateway.audit logger; the router and server access logs are off because request lines carry codes.

Sources: Dockerfile, Compose file, health route, server start, and the pod contract's assumptions.

The repository's README lists one remaining production-readiness stage: a closing security review of the production deployment shape.

Warning

The gateway's signing key lets its holder issue tokens that DIAL Core accepts for any user. Deliver it from a secret store, never bake it into an image, and rotate it as described in Key rotation.