Copy page

Identity providers

Configuring Clerk

The MCP Gateway can use Clerk as the identity provider behind its downstream OAuth flow. The mcp-clerk-oauth-inbound policy is a Clerk-friendly wrapper around the generic mcp-oauth-inbound policy: provide your Clerk Frontend API URL, a client ID, and a client secret, and the policy derives the OIDC issuer, JWKS URL, and authorize and token URLs for you.

This guide walks through the Clerk dashboard setup, then wires the policy into a gateway project. Read the authentication overview first for the two-layer OAuth model.

Set up Clerk

The MCP Gateway acts as an OAuth 2.1 authorization server in front of Clerk. Clerk handles browser login; the gateway issues its own access tokens that bind to MCP routes.

Create an OAuth application

1. In the Clerk Dashboard, switch to the instance you want the gateway to use, then open Configure → OAuth Applications.
2. Click Add OAuth application.
3. Give the application a name (for example, Zuplo MCP Gateway).
4. Set Redirect URIs to https://<gateway-host>/oauth/callback. Add http://localhost:9000/oauth/callback for local development with zuplo dev.
5. Select the OIDC scopes the gateway needs — openid, profile, and email are enough.
6. Click Save.

Note the Client ID and Client Secret from the application's detail page. You'll wire these into the policy in the next section.

Find the Frontend API URL

Open Configure → Domains in the Clerk Dashboard. The Frontend API URL is shown at the top — it looks like https://verb-noun-00.clerk.accounts.dev on development instances or https://clerk.example.com on production instances with a custom domain. Copy the origin (no trailing path).

Wire the policy into the gateway

Add the policy to config/policies.json:

Code
{
  "name": "clerk-managed-oauth",
  "policyType": "mcp-clerk-oauth-inbound",
  "handler": {
    "module": "$import(@zuplo/runtime/mcp-gateway)",
    "export": "McpClerkOAuthInboundPolicy",
    "options": {
      "frontendApiUrl": "$env(CLERK_FRONTEND_API_URL)",
      "clientId": "$env(CLERK_CLIENT_ID)",
      "clientSecret": "$env(CLERK_CLIENT_SECRET)"
    }
  }
}

Set the three environment variables in your project's environment configuration. CLERK_FRONTEND_API_URL goes in plain config; the secret values belong in the project secret store.

Attach the policy to each MCP route in config/routes.oas.json:

Code
{
  "paths": {
    "/mcp/linear-v1": {
      "get,post": {
        "operationId": "linear-mcp-server",
        "x-zuplo-route": {
          "corsPolicy": "none",
          "handler": {
            "module": "$import(@zuplo/runtime/mcp-gateway)",
            "export": "McpProxyHandler",
            "options": {
              "rewritePattern": "https://mcp.linear.app/mcp",
            },
          },
          "policies": {
            "inbound": ["clerk-managed-oauth", "mcp-token-exchange-linear"],
          },
        },
      },
    },
  },
}

Register the gateway plugin in modules/zuplo.runtime.ts:

Code
import { RuntimeExtensions } from "@zuplo/runtime";
import { McpGatewayPlugin } from "@zuplo/runtime/mcp-gateway";

export function runtimeInit(runtime: RuntimeExtensions) {
  runtime.addPlugin(new McpGatewayPlugin());
}

What the wrapper derives

Generic field	Derived value
oidc.issuer	{frontendApiUrl}
oidc.jwksUrl	{frontendApiUrl}/.well-known/jwks.json
browserLogin.url	{frontendApiUrl}/oauth/authorize
browserLogin.tokenUrl	{frontendApiUrl}/oauth/token

Test the configuration

The fastest sanity check is to connect an MCP client:

1. Open Claude Desktop, Cursor, Claude Code, or another OAuth-aware MCP client.
2. Add a remote MCP server pointing at one of your /mcp/{slug} routes.
3. The client should redirect you to Clerk's login page. After login, the gateway's consent screen renders. Approve it.
4. The client receives an access token and can call tools/list.

If something fails partway through, walk the flow manually using the manual OAuth testing guide — it exercises every endpoint with curl so you can see the raw responses.

Common issues

• The policy rejects frontendApiUrl at boot. The value includes a path, query string, or fragment. Use only the origin (https://clerk.example.com).
• Browser login redirects but the callback fails. The https://<gateway-host>/oauth/callback URL isn't on the OAuth application's redirect URIs allow-list in Clerk.

Related

• Authentication overview
• Configuring a generic OIDC provider
• Per-user OAuth to upstream MCP servers