Zuplo
MCP

MCP Gateway Plugin

McpGatewayPlugin activates the MCP Gateway internal routes on the runtime router: the OAuth authorization server, upstream connection management, well-known metadata endpoints, and the read-only MCP Server Registry. When no MCP-related policy is present, the plugin registers no OAuth routes — it still records plugin.mcp-gateway feature usage on construction so gateway adoption is visible in telemetry.

Importing from @zuplo/runtime/mcp-gateway is the opt-in: the runtime core doesn't depend on MCP Gateway code until the plugin is added.

Registration

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

TypeScriptmodules/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 accepts an optional configuration object. All options have defaults, so the no-argument form works for most projects.

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

export function runtimeInit(runtime: RuntimeExtensions) {
  runtime.addPlugin(
    new McpGatewayPlugin({
      basePath: "/__zuplo",
      registry: {
        enabled: true,
        path: "/mcp-registry",
      },
    }),
  );
}

Options

OptionTypeDefaultDescription
basePathstring"/__zuplo"Base path for all gateway internal routes (OAuth, well-known, registry). Must start with / and can't collide with route paths.
registryMcpGatewayRegistryOptionsSee belowConfigures the read-only MCP Server Registry.

basePath

The base path prefixes every internal URL the gateway serves — OAuth endpoints (/oauth/*), well-known metadata (/.well-known/*), and the registry mount (/mcp-registry). With the default "/__zuplo", the token endpoint lives at /__zuplo/oauth/token and the registry at /__zuplo/mcp-registry.

TypeScriptCode
new McpGatewayPlugin({ basePath: "/internal" });
// OAuth token:  /internal/oauth/token
// Registry:     /internal/mcp-registry

registry

Configures the read-only MCP Server Registry API (v0.1) that advertises the gateway's registered MCP routes. See MCP Server Registry for the endpoint reference and behavior.

OptionTypeDefaultDescription
enabledbooleantrueSet to false to disable the registry entirely. No registry routes are registered when disabled.
pathstring"{basePath}/mcp-registry"Absolute URL path where the registry API mounts. Registry endpoints live below this path (for example, {path}/v0.1/servers). Validated like basePath.

The registry path is validated with the same schema as basePath, plus a boot-time guard that rejects mounts shadowing the OAuth discovery (/.well-known) or authorize wildcard routes.

When registry.enabled is false, the path collision guard is skipped — a disabled registry registers no routes and must not fail boot over a mount that will never exist.

Default mount

With the default basePath of "/__zuplo" and no registry override, the registry is served at:

Code
/__zuplo/mcp-registry/v0.1/servers

Custom registry path

Set registry.path to mount the registry independently of basePath:

TypeScriptCode
new McpGatewayPlugin({
  registry: { path: "/registry" },
});
// Registry:  /registry/v0.1/servers
// OAuth:     /__zuplo/oauth/token  (basePath unchanged)

Disabled registry

Turn off the registry if you don't need server discovery:

TypeScriptCode
new McpGatewayPlugin({
  registry: { enabled: false },
});

Related

Last modified on
MCP SDKNode Modules