zuplo 7.4.4 → 7.4.5

package/docs/mcp-gateway/introduction.mdx

@@ -32,7 +32,9 @@ prompt injection or token misuse. Each gateway feature maps to one of five
 problems that show up the moment a team uses more than one or two MCP servers:
 
 1. **Discovery.** A single catalog of approved MCP servers your developers and
-   agents can connect to. No more sharing OAuth client IDs in Slack.
+   agents can connect to. The gateway serves a read-only
+   [MCP Server Registry](./server-registry.mdx) API that advertises every
+   registered MCP route — no more sharing OAuth client IDs in Slack.
 2. **Authentication.** Translation from your corporate SSO to whatever each
    upstream MCP requires. MCP client config files no longer hold raw upstream
    credentials.

package/docs/mcp-gateway/quickstart-local.mdx

@@ -91,7 +91,7 @@ older project and the build complains about the compatibility date, see
            "jwksUrl": "http://127.0.0.1:9000/.well-known/jwks.json"
          },
          "browserLogin": {
-           "url": "http://127.0.0.1:9000/oauth/dev-login"
+           "url": "http://127.0.0.1:9000/__zuplo/oauth/dev-login"
          }
        }
      }
@@ -100,12 +100,12 @@ older project and the build complains about the compatibility date, see
 
    :::caution
 
-   `/oauth/dev-login` returns `403 Forbidden` for any request that doesn't
-   arrive over loopback, so it's safe to leave configured, but only useful in
-   local dev. Production deployments should use a real OIDC provider through one
-   of the [IdP wrappers](./auth/overview.mdx#identity-providers). A common
-   pattern is keeping two OAuth policies (one for production, one for dev) and
-   selecting between them in `routes.oas.json` by environment.
+   `/__zuplo/oauth/dev-login` returns `403 Forbidden` for any request that
+   doesn't arrive over loopback, so it's safe to leave configured, but only
+   useful in local dev. Production deployments should use a real OIDC provider
+   through one of the [IdP wrappers](./auth/overview.mdx#identity-providers). A
+   common pattern is keeping two OAuth policies (one for production, one for
+   dev) and selecting between them in `routes.oas.json` by environment.
 
    :::
 

package/docs/mcp-gateway/reference.mdx

@@ -16,37 +16,70 @@ The URLs below are all relative to the gateway origin. For a project deployed to
 `https://my-gateway.zuplo.dev` with an MCP route at `/mcp/linear-v1`, the public
 route is `https://my-gateway.zuplo.dev/mcp/linear-v1`.
 
+The gateway mounts its internal OAuth and upstream-connection action routes
+under the `basePath` configured on the `McpGatewayPlugin`. The default base path
+is `/__zuplo`, which keeps gateway endpoints out of your API's route namespace.
+Discovery documents (`/.well-known/…`) always stay at the origin root because
+RFC 8414 / RFC 9728 locate them relative to the issuer. Pass `basePath: "/"` in
+the plugin options to mount action routes at the origin root instead.
+
 ### Well-known metadata
 
 | Path                                                   | Methods          | Purpose                                                                                                                                                                                        |
 | ------------------------------------------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `/.well-known/oauth-authorization-server`              | `GET`, `OPTIONS` | RFC 8414 Authorization Server metadata for the gateway. Issuer is the gateway origin.                                                                                                          |
-| `/.well-known/oauth-authorization-server/{routePath*}` | `GET`, `OPTIONS` | Per-route AS metadata. The issuer is rebound to the route's canonical URI, and `authorization_endpoint` points at `/oauth/authorize/{routePath}`.                                              |
+| `/.well-known/oauth-authorization-server/{routePath*}` | `GET`, `OPTIONS` | Per-route AS metadata. The issuer is rebound to the route's canonical URI, and `authorization_endpoint` points at `{basePath}/oauth/authorize/{routePath}`.                                    |
 | `/.well-known/oauth-protected-resource/{routePath*}`   | `GET`, `OPTIONS` | RFC 9728 Protected Resource Metadata for an MCP route. Lists `resource`, `resource_name`, `authorization_servers`, `bearer_methods_supported`, `scopes_supported`, and `mcp_protocol_version`. |
-| `/.well-known/oauth-client/{connection}`               | `GET`            | OAuth Client ID Metadata Document the gateway hosts to identify itself to an upstream provider. Requires the `?authProfileId=` query parameter.                                                |
 
 These routes are CORS-permissive (`Access-Control-Allow-Origin: *`) because
 spec-compliant browser-resident MCP clients fetch them cross-origin.
 
 ### OAuth endpoints
 
-| Path                            | Methods       | Purpose                                                                                                                                                                                  |
-| ------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `/oauth/register`               | `POST`        | RFC 7591 Dynamic Client Registration. Supports `none`, `client_secret_basic`, `client_secret_post`, and `private_key_jwt` token-endpoint auth methods. DCR clients expire after 90 days. |
-| `/oauth/authorize`              | `GET`         | Gateway-wide authorization endpoint. Requires the `resource` parameter unless exactly one MCP route is configured.                                                                       |
-| `/oauth/authorize/{routePath*}` | `GET`         | Per-route authorization endpoint. The `resource` is implicit from the path.                                                                                                              |
-| `/oauth/callback`               | `GET`         | Browser-login callback from the configured identity provider. Renders the consent page.                                                                                                  |
-| `/oauth/setup`                  | `GET`, `POST` | Consent screen. Lists the upstream the requested MCP route depends on. `POST` accepts `decision=continue` / `approve` / `cancel`.                                                        |
-| `/oauth/token`                  | `POST`        | RFC 6749 token endpoint. Supports `authorization_code` and `refresh_token` grants.                                                                                                       |
-| `/oauth/revoke`                 | `POST`        | RFC 7009 revocation endpoint. Accepts public-client revocations without authentication.                                                                                                  |
-| `/oauth/dev-login`              | `GET`         | Loopback-only dev shortcut. Returns `403` over non-loopback addresses.                                                                                                                   |
+Paths below use the default `basePath` of `/__zuplo`. Substitute your configured
+`basePath` if you changed it.
+
+| Path                                             | Methods       | Purpose                                                                                                                                                                                  |
+| ------------------------------------------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/__zuplo/oauth/register`                        | `POST`        | RFC 7591 Dynamic Client Registration. Supports `none`, `client_secret_basic`, `client_secret_post`, and `private_key_jwt` token-endpoint auth methods. DCR clients expire after 90 days. |
+| `/__zuplo/oauth/authorize`                       | `GET`         | Gateway-wide authorization endpoint. Requires the `resource` parameter unless exactly one MCP route is configured.                                                                       |
+| `/__zuplo/oauth/authorize/{routePath*}`          | `GET`         | Per-route authorization endpoint. The `resource` is implicit from the path.                                                                                                              |
+| `/__zuplo/oauth/callback`                        | `GET`         | Browser-login callback from the configured identity provider. Renders the consent page.                                                                                                  |
+| `/__zuplo/oauth/setup`                           | `GET`, `POST` | Consent screen. Lists the upstream the requested MCP route depends on. `POST` accepts `decision=continue` / `approve` / `cancel`.                                                        |
+| `/__zuplo/oauth/token`                           | `POST`        | RFC 6749 token endpoint. Supports `authorization_code` and `refresh_token` grants.                                                                                                       |
+| `/__zuplo/oauth/revoke`                          | `POST`        | RFC 7009 revocation endpoint. Accepts public-client revocations without authentication.                                                                                                  |
+| `/__zuplo/oauth/dev-login`                       | `GET`         | Loopback-only dev shortcut. Returns `403` over non-loopback addresses.                                                                                                                   |
+| `/__zuplo/.well-known/oauth-client/{connection}` | `GET`         | OAuth Client ID Metadata Document the gateway hosts to identify itself to an upstream provider. Requires the `?authProfileId=` query parameter.                                          |
 
 ### Upstream connection endpoints
 
-| Path                                      | Methods | Purpose                                                                                                                                                                |
-| ----------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `/auth/connections/{connection}/connect`  | `GET`   | Browser entry to the upstream OAuth flow. With `redirect=true`, returns a 302 to the upstream `/authorize`; otherwise returns `428` with the connect-required payload. |
-| `/auth/connections/{connection}/callback` | `GET`   | Upstream OAuth callback. Renders a success or failure page.                                                                                                            |
+| Path                                              | Methods | Purpose                                                                                                                                                                |
+| ------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/__zuplo/auth/connections/{connection}/connect`  | `GET`   | Browser entry to the upstream OAuth flow. With `redirect=true`, returns a 302 to the upstream `/authorize`; otherwise returns `428` with the connect-required payload. |
+| `/__zuplo/auth/connections/{connection}/callback` | `GET`   | Upstream OAuth callback. Renders a success or failure page.                                                                                                            |
+
+### MCP Server Registry
+
+The gateway serves a read-only
+[MCP Server Registry API](https://github.com/modelcontextprotocol/registry)
+(v0.1) that advertises every MCP route. Enabled by default; see
+[Server Registry](./server-registry.mdx) for the endpoint reference and
+[`McpGatewayPlugin`](../programmable-api/mcp-gateway-plugin.mdx#registry) for
+configuration.
+
+| Path                                                                 | Methods          | Purpose                                                                |
+| -------------------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------- |
+| `{registryPath}/v0.1/servers`                                        | `GET`, `OPTIONS` | List servers with `cursor`/`limit`/`search`/`version`/`updated_since`. |
+| `{registryPath}/v0.1/servers/{serverName}/versions`                  | `GET`, `OPTIONS` | List versions for a single server.                                     |
+| `{registryPath}/v0.1/servers/{serverName}/versions/{version}`        | `GET`, `OPTIONS` | Get a specific version (supports `latest` alias).                      |
+| `{registryPath}/v0.1/publish`                                        | `POST`           | `501` — publishing is optional in the spec and not supported.          |
+| `{registryPath}/v0.1/servers/{serverName}/versions/{version}`        | `PUT`, `DELETE`  | `501` — version update/delete is optional in the spec.                 |
+| `{registryPath}/v0.1/servers/{serverName}/versions/{version}/status` | `PATCH`          | `403` — no publish/edit permissions.                                   |
+| `{registryPath}/v0.1/servers/{serverName}/status`                    | `PATCH`          | `403` — no publish/edit permissions.                                   |
+
+`{registryPath}` defaults to `/__zuplo/mcp-registry`. Discovery GETs are
+unauthenticated and CORS-permissive. Error bodies use the spec's
+`{"error": "..."}` shape.
 
 ### Customer-defined MCP routes
 
@@ -74,17 +107,17 @@ DCR requests that include any other scope value are rejected with
 | Refresh token / grant                 | ~10 years  | `gateway.refreshTokenTtlSeconds` on the OAuth policy. | Downstream refresh grants are gateway client sessions, not upstream OAuth token lifetimes. The default is intentionally long so the gateway doesn't impose a shorter session bound than the upstream provider's refresh-token policy already does. |
 | DCR-registered client                 | 90 days    | Not configurable.                                     | Encourages clients to use CIMD where possible; stale DCR clients age out automatically.                                                                                                                                                            |
 | Authorization code                    | 60 seconds | Not configurable.                                     | OAuth 2.1 recommendation.                                                                                                                                                                                                                          |
-| `oauth_authorize` state               | 15 minutes | `browserLogin.stateTtlSeconds`.                       | Window between `/oauth/authorize` and `/oauth/callback`.                                                                                                                                                                                           |
+| `oauth_authorize` state               | 15 minutes | `browserLogin.stateTtlSeconds`.                       | Window between `/__zuplo/oauth/authorize` and `/__zuplo/oauth/callback`.                                                                                                                                                                           |
 
 ## Headers
 
 ### Required on requests to MCP routes
 
-| Header                                        | Required                | Notes                                                                               |
-| --------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------- |
-| `Authorization: Bearer <token>`               | Yes (after initial 401) | Opaque access token issued by `/oauth/token`. Tokens in query strings are rejected. |
-| `Accept: application/json, text/event-stream` | Yes                     | Per the Streamable HTTP transport spec. The gateway forwards the body as-is.        |
-| `MCP-Protocol-Version: 2025-11-25`            | Yes after `initialize`  | Per the MCP spec. The gateway tracks the current MCP protocol revision.             |
+| Header                                        | Required                | Notes                                                                                       |
+| --------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------- |
+| `Authorization: Bearer <token>`               | Yes (after initial 401) | Opaque access token issued by `/__zuplo/oauth/token`. Tokens in query strings are rejected. |
+| `Accept: application/json, text/event-stream` | Yes                     | Per the Streamable HTTP transport spec. The gateway forwards the body as-is.                |
+| `MCP-Protocol-Version: 2025-11-25`            | Yes after `initialize`  | Per the MCP spec. The gateway tracks the current MCP protocol revision.                     |
 
 ### Honored when present
 
@@ -119,9 +152,9 @@ See [Compatibility dates](./code-config/compatibility-dates.mdx).
 In addition to the standard RFC 8414 / OIDC discovery fields, the gateway
 publishes a vendor extension:
 
-| Field                        | Type   | Values                            | Purpose                                                                                                              |
-| ---------------------------- | ------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `x-zuplo-browser-login-kind` | string | `"federated_oidc"`, `"local_dev"` | Lets client tooling special-case local development configurations (which use `/oauth/dev-login` and a loopback IdP). |
+| Field                        | Type   | Values                            | Purpose                                                                                                                      |
+| ---------------------------- | ------ | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `x-zuplo-browser-login-kind` | string | `"federated_oidc"`, `"local_dev"` | Lets client tooling special-case local development configurations (which use `/__zuplo/oauth/dev-login` and a loopback IdP). |
 
 ## Public route URL pattern
 

package/docs/mcp-gateway/server-registry.mdx

@@ -0,0 +1,179 @@
+---
+title: "MCP Server Registry"
+sidebar_label: "Server Registry"
+description:
+  The read-only MCP Server Registry API (v0.1) the gateway serves by default —
+  advertises every MCP route so clients and subregistries can discover them
+  without authentication.
+---
+
+The MCP Gateway serves a read-only
+[MCP Server Registry API](https://github.com/modelcontextprotocol/registry)
+(v0.1 freeze) that advertises every MCP route on the gateway. MCP clients and
+mirroring subregistries can discover the gateway's registered servers without
+authentication, per the registry specification.
+
+The registry is enabled by default and mounted at `/__zuplo/mcp-registry` (with
+the default `basePath`). Configure or disable it through the
+[`registry` option](../programmable-api/mcp-gateway-plugin.mdx#registry) on
+`McpGatewayPlugin`.
+
+## What gets listed
+
+The registry projects one entry per MCP-serving route — both:
+
+- **Gateway virtual servers** — routes that carry MCP gateway policies
+  (`mcp-oauth-inbound` / `mcp-token-exchange-inbound`) and use
+  [`McpProxyHandler`](./code-config/mcp-proxy-handler.mdx) to proxy to an
+  upstream MCP server.
+- **Standalone MCP servers** — routes that use the built-in `mcpServerHandler`
+  or a bare `McpProxyHandler` without gateway policies.
+
+Each entry includes:
+
+| Field         | Source                                                                                                            |
+| ------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `name`        | `<reverse-DNS of request host>/<operationId>` (for example, `com.example.gateway/linear-mcp-server`)              |
+| `remotes`     | The gateway route URL, using the `streamable-http` transport.                                                     |
+| `description` | OpenAPI operation `description` or `summary`, clamped to 100 code points per the spec.                            |
+| `title`       | `mcpServerHandler` options or the OpenAPI operation `summary`.                                                    |
+| `version`     | `mcpServerHandler` options or upstream connection config. Range-like values (`^1.2.3`, `1.x`) project as `0.0.0`. |
+| `websiteUrl`  | Upstream connection config, canonicalized to a valid URI.                                                         |
+| `icons`       | Upstream connection config. Only HTTPS URLs are included; `src` is clamped to 255 characters.                     |
+
+:::note
+
+Server names are derived from the request host — the same posture as the OAuth
+issuer and Protected Resource Metadata. Names vary with the hostname the gateway
+is reached on, so a custom domain produces different names than the default
+`*.zuplo.dev` origin.
+
+:::
+
+The projection never throws. Every spec constraint is enforced by sanitizing or
+omitting: names longer than 200 characters are truncated with a hash suffix,
+descriptions are clamped, non-HTTPS icons are dropped, and version ranges are
+replaced with `0.0.0`. One malformed route can't take down discovery for the
+rest.
+
+Parameterized routes (for example, `/mcp/{server}`) are omitted from the
+directory — a templated path is not a concretely connectable remote.
+
+## Endpoints
+
+All paths are relative to the registry mount (default: `/__zuplo/mcp-registry`).
+Discovery GETs are unauthenticated and CORS-permissive
+(`Access-Control-Allow-Origin: *`).
+
+### `GET {path}/v0.1/servers`
+
+Lists all MCP servers registered on the gateway.
+
+| Query parameter | Type    | Default | Description                                                                                     |
+| --------------- | ------- | ------- | ----------------------------------------------------------------------------------------------- |
+| `cursor`        | string  | —       | Opaque pagination cursor from a previous response.                                              |
+| `limit`         | integer | `30`    | Maximum servers to return. Clamped to `100`.                                                    |
+| `search`        | string  | —       | Case-insensitive substring filter on server name.                                               |
+| `version`       | string  | —       | Filter to servers matching a specific version.                                                  |
+| `updated_since` | string  | —       | RFC 3339 date-time. Validated but never filters — every entry conservatively counts as changed. |
+
+Response:
+
+```json
+{
+  "servers": [
+    {
+      "name": "com.example.gateway/linear-mcp-server",
+      "description": "Linear MCP proxy",
+      "title": "Linear",
+      "version": "1.0.0",
+      "remotes": [
+        {
+          "type": "streamable-http",
+          "url": "https://gateway.example.com/mcp/linear-v1"
+        }
+      ],
+      "websiteUrl": "https://linear.app",
+      "icons": []
+    }
+  ],
+  "metadata": { "count": 1 }
+}
+```
+
+When `cursor` is present in the response, more results are available. Pass it
+back as the `cursor` query parameter on the next request.
+
+### `GET {path}/v0.1/servers/{serverName}/versions`
+
+Lists versions for a single server. With the current read-only projection, every
+server has exactly one version entry.
+
+`{serverName}` is URL-encoded — the slash in the reverse-DNS name is sent as
+`%2F` (for example, `com.example.gateway%2Flinear-mcp-server`).
+
+### `GET {path}/v0.1/servers/{serverName}/versions/{version}`
+
+Returns a single server version. The special alias `latest` resolves to the
+server's current version.
+
+### Write endpoints (refused)
+
+The registry is read-only. Write endpoints are refused per the spec:
+
+| Endpoint                                                     | Method   | Status | Reason                                                                                       |
+| ------------------------------------------------------------ | -------- | ------ | -------------------------------------------------------------------------------------------- |
+| `{path}/v0.1/publish`                                        | `POST`   | `501`  | Spec marks publishing optional and documents `501`.                                          |
+| `{path}/v0.1/servers/{serverName}/versions/{version}`        | `PUT`    | `501`  | Spec marks version update optional.                                                          |
+| `{path}/v0.1/servers/{serverName}/versions/{version}`        | `DELETE` | `501`  | Spec marks version deletion optional.                                                        |
+| `{path}/v0.1/servers/{serverName}/versions/{version}/status` | `PATCH`  | `403`  | Spec defines no `501` for status operations; returns `403` with a permissions error message. |
+| `{path}/v0.1/servers/{serverName}/status`                    | `PATCH`  | `403`  | Same as above.                                                                               |
+
+All error bodies use the spec's `{"error": "..."}` shape — not RFC 7807 problem
+details — so off-the-shelf registry clients can parse them. A catch-all under
+the mount ensures even unrecognized requests get the spec-shaped `404`.
+
+## Configuration
+
+The registry is configured through the `McpGatewayPlugin` constructor. See the
+[`registry` option](../programmable-api/mcp-gateway-plugin.mdx#registry) for the
+full options reference.
+
+```ts title="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({
+      registry: {
+        enabled: true, // default
+        path: "/mcp-registry", // default: "{basePath}/mcp-registry"
+      },
+    }),
+  );
+}
+```
+
+## Limitations
+
+- **No publishing.** The registry is a read-only projection of the gateway's
+  live route configuration. There is no write path, no namespace-ownership
+  model, and no stored `publishedAt` or `updatedAt` timestamps.
+- **`updated_since` validates but never filters.** Because the registry is
+  derived from route config with no stored timestamps, every entry
+  conservatively counts as changed. This keeps mirroring subregistries correct
+  at the cost of re-reading everything.
+- **No deployment-pinned server identity.** Server names are derived from the
+  request host, not from a stable deployment-level identifier.
+
+## Related
+
+- [`McpGatewayPlugin` reference](../programmable-api/mcp-gateway-plugin.mdx) —
+  the full plugin options, including `basePath` and `registry`.
+- [Gateway reference](./reference.mdx) — the full URL catalog, including the
+  registry mount.
+- [How the MCP Gateway works](./how-it-works.mdx) — architecture and request
+  lifecycle.
+- [MCP Server Registry specification](https://github.com/modelcontextprotocol/registry)
+  — the v0.1 freeze the gateway implements.

package/docs/mcp-gateway/test-clients.mdx

@@ -102,8 +102,8 @@ Whichever tool you pick, exercise these gateway behaviors during a smoke test:
    `WWW-Authenticate: Bearer resource_metadata=...`. If it doesn't, the route is
    missing an MCP OAuth policy.
 2. **OAuth handshake completes.** Confirm the inspector lands on the gateway's
-   `/oauth/setup` consent page (rendered HTML), that the upstream's **Connect**
-   button works, and that the inspector receives an access token.
+   `/__zuplo/oauth/setup` consent page (rendered HTML), that the upstream's
+   **Connect** button works, and that the inspector receives an access token.
 3. **`tools/list` returns the expected curated set.** If you've attached
    `mcp-capability-filter-inbound`, verify the filter is working — only
    allow-listed tools should appear.

package/docs/mcp-server/custom-tools.mdx

@@ -432,6 +432,36 @@ export default async function (request: ZuploRequest, context: ZuploContext) {
 }
 ```
 
+## Controlling tool results with ZuploMcpSdk
+
+By default, the MCP Server handler serializes the downstream response body into
+a single text content block and, when `includeStructuredContent` is enabled,
+derives `structuredContent` from it. The `ZuploMcpSdk` class gives you
+programmatic control over what the AI client receives — without changing the
+response your handler returns.
+
+The most common use case is a **compact summary**: replace the full serialized
+body in `content` with a short human-readable summary, while the gateway still
+auto-derives `structuredContent` from the downstream response. This reduces the
+token count in the model's context without losing data.
+
+```typescript
+import { ZuploContext, ZuploMcpSdk, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const response = await context.invokeRoute("/todos");
+  new ZuploMcpSdk(context).setRawCallToolResult({
+    content: [{ type: "text", text: "Fetched the todo list" }],
+  });
+  return response;
+}
+```
+
+You can also read metadata from the incoming `tools/call` request using
+`getRawCallToolRequest()`, and override `structuredContent` and `_meta`
+independently. For the full API reference, see
+[ZuploMcpSdk](../programmable-api/mcp-sdk.mdx).
+
 ## Best Practices
 
 ### Tool Design
@@ -479,6 +509,8 @@ export default async function (request: ZuploRequest, context: ZuploContext) {
 
 ## Learn More
 
+- [ZuploMcpSdk](../programmable-api/mcp-sdk.mdx) - Programmatic control over MCP
+  tool results
 - [MCP Server Handler](../handlers/mcp-server.mdx) - For simple route-to-tool
   mapping
 - [Model Context Protocol Overview](../mcp-server/introduction.mdx) -

package/docs/programmable-api/mcp-gateway-plugin.mdx

@@ -0,0 +1,137 @@
+---
+title: "MCP Gateway Plugin"
+sidebar_label: "MCP Gateway Plugin"
+description:
+  Reference for the McpGatewayPlugin runtime plugin — options for the base path,
+  OAuth endpoints, and the read-only MCP Server Registry.
+---
+
+`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](../mcp-gateway/server-registry.mdx). 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`:
+
+```ts title="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 accepts an optional configuration object. All options have defaults,
+so the no-argument form works for most projects.
+
+```ts title="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({
+      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](../mcp-gateway/server-registry.mdx).                                              |
+
+### `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`.
+
+```ts
+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](../mcp-gateway/server-registry.mdx) 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.
+
+:::note
+
+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:
+
+```text
+/__zuplo/mcp-registry/v0.1/servers
+```
+
+#### Custom registry path
+
+Set `registry.path` to mount the registry independently of `basePath`:
+
+```ts
+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:
+
+```ts
+new McpGatewayPlugin({
+  registry: { enabled: false },
+});
+```
+
+## Related
+
+- [MCP Server Registry](../mcp-gateway/server-registry.mdx) — the read-only
+  registry API the plugin serves by default.
+- [Set up an MCP Gateway](../mcp-gateway/code-config/overview.mdx) — the how-to
+  that puts this plugin into a project with policies and routes.
+- [How the MCP Gateway works](../mcp-gateway/how-it-works.mdx) — the
+  architecture and request lifecycle.
+- [Gateway reference](../mcp-gateway/reference.mdx) — the full URL catalog,
+  default TTLs, and configuration constants.