MCP Clerk OAuth Policy

Use Clerk as the identity provider for MCP Gateway browser login.

Configuration

The configuration shows how to configure the policy in the 'policies.json' document.

config/policies.json
{
  "name": "my-mcp-clerk-oauth-inbound-policy",
  "policyType": "mcp-clerk-oauth-inbound",
  "handler": {
    "export": "McpClerkOAuthInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "browserLoginOverrides": {
        "remoteTimeoutMs": 10000,
        "sessionTtlSeconds": 28800,
        "stateTtlSeconds": 900
      },
      "clientId": "$env(CLERK_CLIENT_ID)",
      "clientSecret": "$env(CLERK_CLIENT_SECRET)",
      "frontendApiUrl": "https://verb-noun-00.clerk.accounts.dev",
      "gateway": {
        "accessTokenTtlSeconds": 900,
        "cimdEnabled": true,
        "refreshTokenTtlSeconds": 2592000
      },
      "scope": "openid profile email"
    }
  }
}

Policy Configuration

• name <string> - The name of your policy instance. This is used as a reference in your routes.
• policyType <string> - The identifier of the policy. This is used by the Zuplo UI. Value should be mcp-clerk-oauth-inbound.
• handler.export <string> - The name of the exported type. Value should be McpClerkOAuthInboundPolicy.
• handler.module <string> - The module containing the policy. Value should be $import(@zuplo/runtime).
• handler.options <object> - The options for this policy. See Policy Options below.

Policy Options

The options for this policy are specified below. All properties are optional unless specifically marked as required.

• frontendApiUrl (required) <string> - The Clerk Frontend API URL origin, without a trailing path, query string, or fragment.
• clientId (required) <string> - The Clerk OAuth application client_id registered for the gateway's browser login flow.
• clientSecret (required) <string> - The Clerk OAuth application client_secret. Use $env(...) to source from a secret environment variable.
• scope <string> - OIDC scopes requested during browser login. Defaults to "openid profile email".
• gateway <object> - Gateway-side OAuth token settings. The gateway issuer and advertised URLs are derived from the incoming request origin.
  • accessTokenTtlSeconds <integer> - Lifetime of access tokens issued by /oauth/token. Defaults to 900.
  • refreshTokenTtlSeconds <integer> - Lifetime of refresh tokens issued by /oauth/token. Defaults to 2592000.
  • cimdEnabled <boolean> - Whether to advertise client_id_metadata_document_supported in AS metadata. Defaults to true.
• browserLoginOverrides <object> - Optional overrides for the derived browser-login settings.
  • remoteTimeoutMs <integer> - No description available. Defaults to 10000.
  • stateTtlSeconds <integer> - No description available. Defaults to 900.
  • sessionTtlSeconds <integer> - No description available. Defaults to 28800.

Using the Policy

MCP Clerk OAuth

Authenticates MCP clients with gateway-issued OAuth tokens and delegates browser login to a Clerk OAuth application.

Configure a Clerk OAuth application in the Clerk Dashboard, add the gateway callback URL as an allowed redirect URI, then provide the Clerk Frontend API URL and OAuth client credentials to this policy.

Code
{
  "name": "clerk-inbound",
  "policyType": "mcp-clerk-oauth-inbound",
  "handler": {
    "export": "McpClerkOAuthInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "frontendApiUrl": "https://verb-noun-00.clerk.accounts.dev",
      "clientId": "$env(CLERK_CLIENT_ID)",
      "clientSecret": "$env(CLERK_CLIENT_SECRET)"
    }
  }
}

The policy derives:

• issuer: {frontendApiUrl}
• JWKS URL: {frontendApiUrl}/.well-known/jwks.json
• authorize URL: {frontendApiUrl}/oauth/authorize
• token URL: {frontendApiUrl}/oauth/token

frontendApiUrl must be the origin only. Do not include a path, query string, fragment, or userinfo.

Read more about how policies work