Copy page

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:

Code
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.

Code
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

Option	Type	Default	Description
basePath	string	"/__zuplo"	Base path for all gateway internal routes (OAuth, well-known, registry). Must start with / and can't collide with route paths.
registry	McpGatewayRegistryOptions	See below	Configures 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.

Code
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.

Option	Type	Default	Description
enabled	boolean	true	Set to false to disable the registry entirely. No registry routes are registered when disabled.
path	string	"{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.

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:

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

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

Related

• MCP Server Registry — the read-only registry API the plugin serves by default.
• Set up an MCP Gateway — the how-to that puts this plugin into a project with policies and routes.
• How the MCP Gateway works — the architecture and request lifecycle.
• Gateway reference — the full URL catalog, default TTLs, and configuration constants.