MCP Gateway quickstart (Local Dev)

Register the MCP Gateway plugin

Open modules/zuplo.runtime.ts (create it if it doesn't exist) 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 OAuth policy with the dev-login shortcut

Setting up a real identity provider for local development is friction. You'd register a loopback callback, manage test users, and so on. The gateway exposes a loopback-only shortcut that skips the IdP round-trip entirely and signs you in as a fixed dev-browser-user.

Open config/policies.json and add the generic OAuth policy pointed at the dev-login URL:

config/policies.json
{
  "name": "dev-oauth",
  "policyType": "mcp-oauth-inbound",
  "handler": {
    "module": "$import(@zuplo/runtime/mcp-gateway)",
    "export": "McpOAuthInboundPolicy",
    "options": {
      "oidc": {
        "issuer": "http://127.0.0.1:9000",
        "jwksUrl": "http://127.0.0.1:9000/.well-known/jwks.json"
      },
      "browserLogin": {
        "url": "http://127.0.0.1:9000/oauth/dev-login"
      }
    }
  }
}

When you do switch to a real provider, its policy reads credentials from $env(...) references. Define those values in a .env file at the project root:

.env
MCP_AUTH0_DOMAIN=your-tenant.us.auth0.com
MCP_AUTH0_CLIENT_ID=your-auth0-web-app-client-id
MCP_AUTH0_CLIENT_SECRET=your-auth0-web-app-client-secret

.env is read when npm run dev starts, so restart the dev server after adding or changing a variable. Never commit .env. Check in a .env.example with placeholder values instead. The dev-login shortcut above needs no environment variables, so you can skip this until you wire up a provider.

Add a token-exchange policy for the upstream

Each OAuth-protected upstream gets its own mcp-token-exchange-inbound policy. It 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, so no upstream client credentials 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 runs 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": ["dev-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, so pick it once and don't change it. The path is whatever you set; /mcp/<provider>-v<n> is the convention.

Run the gateway

From the project root:

Code
npm run dev

The route is now reachable at http://127.0.0.1:9000/mcp/linear-v1.

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}'

Connect Claude Desktop

Open Claude Desktop, go to Settings → Connectors, scroll to the bottom, and click Add custom connector. Paste http://127.0.0.1:9000/mcp/linear-v1 and click Add.

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

1. The dev-login shortcut signs you in without any IdP prompt.
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.

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" works well. Claude asks for permission to call the tool, then returns results proxied through the gateway.