MCP Gateway quickstart

Pin the compatibility date

MCP Gateway features require compatibilityDate >= 2026-03-01 in zuplo.jsonc:

zuplo.jsonc
{
  "version": 1,
  "compatibilityDate": "2026-03-01",
}

Existing projects on an older date need to bump it before adding MCP features. New projects default to a recent date, so most won't need to change anything.

Register the MCP Gateway plugin

Add a modules/zuplo.runtime.ts file (or edit the existing one) and register McpGatewayPlugin:

modules/zuplo.runtime.ts
import { RuntimeExtensions } from "@zuplo/runtime";
import { McpGatewayPlugin } from "@zuplo/runtime/mcp-gateway";

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

The plugin registers the OAuth metadata, authorization endpoints, consent page, and upstream connect callbacks the gateway needs.

Add an MCP OAuth policy

Open config/policies.json and add the Auth0 MCP OAuth policy. It authenticates inbound MCP requests against your Auth0 tenant:

config/policies.json
{
  "name": "auth0-managed-oauth",
  "policyType": "mcp-auth0-oauth-inbound",
  "handler": {
    "module": "$import(@zuplo/runtime/mcp-gateway)",
    "export": "McpAuth0OAuthInboundPolicy",
    "options": {
      "auth0Domain": "$env(AUTH0_DOMAIN)",
      "clientId": "$env(AUTH0_CLIENT_ID)",
      "clientSecret": "$env(AUTH0_CLIENT_SECRET)",
    },
  },
}

Set the three environment variables on the project — AUTH0_DOMAIN in plain config and AUTH0_CLIENT_ID / AUTH0_CLIENT_SECRET in the secret store.

Add a token-exchange policy for the upstream

Each OAuth-protected upstream gets its own mcp-token-exchange-inbound policy. The policy looks up the user's upstream credential and attaches it as the upstream Authorization header. Add this entry to config/policies.json:

config/policies.json
{
  "name": "mcp-token-exchange-linear",
  "policyType": "mcp-token-exchange-inbound",
  "handler": {
    "module": "$import(@zuplo/runtime/mcp-gateway)",
    "export": "McpTokenExchangeInboundPolicy",
    "options": {
      "displayName": "Linear",
      "protectedResourceMetadataUrl": "https://mcp.linear.app/.well-known/oauth-protected-resource",
      "authMode": "user-oauth",
      "scopes": [],
      "clientRegistration": { "mode": "auto" },
    },
  },
}

authMode: "user-oauth" means each user connects their own Linear account the first time they call the route. clientRegistration: { "mode": "auto" } lets the gateway register itself with Linear's OAuth server on demand, using OAuth Client ID Metadata Documents with a DCR fallback — no upstream client credentials need to live in source control.

Add the route

Open config/routes.oas.json and add an MCP route. The handler points at Linear's MCP server URL; the inbound policy chain attaches the OAuth policy followed by the token exchange policy:

config/routes.oas.json
{
  "openapi": "3.1.0",
  "info": { "title": "MCP Gateway", "version": "0.1.0" },
  "paths": {
    "/mcp/linear-v1": {
      "get,post": {
        "operationId": "linear-mcp-server",
        "summary": "Linear MCP Proxy",
        "x-zuplo-route": {
          "corsPolicy": "none",
          "handler": {
            "module": "$import(@zuplo/runtime/mcp-gateway)",
            "export": "McpProxyHandler",
            "options": {
              "rewritePattern": "https://mcp.linear.app/mcp",
            },
          },
          "policies": {
            "inbound": ["auth0-managed-oauth", "mcp-token-exchange-linear"],
          },
        },
      },
    },
  },
}

operationId is the stable identifier for the route. It appears in analytics and is part of the per-user upstream connection key — pick it once and don't change it.

Run the gateway

Run zuplo dev from the project root:

Code
zuplo dev

The route is now reachable at http://127.0.0.1:9000/mcp/linear-v1. Deploy when you're ready to expose it publicly; the route then lives at https://<your-deployment>/mcp/linear-v1.

A quick sanity check is to send an unauthenticated POST:

Code
curl -i -X POST http://127.0.0.1:9000/mcp/linear-v1 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

The gateway should return 401 Unauthorized with a WWW-Authenticate header that points at the Protected Resource Metadata URL. If you see that, the OAuth policy is wired up correctly.

Connect Claude Desktop

Open Claude Desktop, go to Settings → Connectors, scroll to the bottom of the list, and click Add custom connector. Paste the route URL — for the locally-running gateway, that's http://127.0.0.1:9000/mcp/linear-v1; for a deployed gateway, use the public URL — and click Add.

Claude Desktop opens the gateway's OAuth flow in a browser:

1. Sign in with Auth0.
2. The gateway's consent page lists Linear with a Connect button.
3. Click Connect, complete Linear's OAuth flow, then click Authorize to finish.

Subsequent requests reuse the issued tokens. For per-client setup details, see Connect MCP clients.

Test it

In Claude Desktop, prompt the model with something that requires Linear — "list my open issues" is a good test. Claude asks for permission to call the tool, then returns results proxied through the gateway.

Open the project's Analytics dashboard and switch to the MCP tab to see the call appear in the events timeline, the success rate, the top capabilities table, and the user breakdown.