Getting Started with MCP Gateway - Editor

Register the MCP Gateway plugin

Open modules/zuplo.runtime.ts (create it if it doesn't exist) and register McpGatewayPlugin:

Code
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

The local dev-login endpoint signs you in as dev-browser-user without an identity provider.

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

Code
{
  "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/jwks"
      },
      "browserLogin": {
        "url": "http://127.0.0.1:9000/__zuplo/oauth/dev-login"
      }
    }
  }
}

The policy requires oidc.issuer and oidc.jwksUrl, but dev-login doesn't use them. Keep these placeholder values for this tutorial; the gateway doesn't serve /jwks.

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:

Code
{
  "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:

Code
{
  "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 project's dev script runs zuplo 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

Use a local stdio bridge so Claude Desktop can reach your local gateway. Native remote connectors connect from Anthropic's servers and cannot reach 127.0.0.1 on your computer.

In Claude Desktop, open Settings → Developer → Edit Config and add this entry to claude_desktop_config.json, preserving any existing servers:

Code
{
  "mcpServers": {
    "Zuplo MCP": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:9000/mcp/linear-v1",
        "--allow-http"
      ]
    }
  }
}

Save the file and restart Claude Desktop. The bridge opens the gateway's OAuth flow on first connection.

In the 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.