zuplo 7.4.4 → 7.4.6

package/docs/mcp-gateway/auth/configuring-auth0.mdx

@@ -56,13 +56,14 @@ tokens that bind to MCP routes. The Auth0 application you create represents the
 ### Configure callback and origin URLs
 
 The gateway completes browser login by redirecting back to its own
-`/oauth/callback` endpoint, so Auth0 needs that URL on its allow-list.
+`/__zuplo/oauth/callback` endpoint, so Auth0 needs that URL on its allow-list.
 
 On the same **Settings** tab:
 
 1. Set **Allowed Callback URLs** to your gateway's
-   `https://<gateway-host>/oauth/callback`. For local development against
-   `zuplo dev`, add `http://localhost:9000/oauth/callback` as well.
+   `https://<gateway-host>/__zuplo/oauth/callback`. For local development
+   against `zuplo dev`, add `http://localhost:9000/__zuplo/oauth/callback` as
+   well.
 2. Set **Allowed Web Origins** to the gateway origin `https://<gateway-host>`
    (plus `http://localhost:9000` for local dev).
 3. Save changes.
@@ -194,8 +195,8 @@ endpoint with `curl` so you can see the raw responses.
 - **"Invalid Auth0 domain" at boot.** The `auth0Domain` value includes a scheme
   prefix or doesn't contain a dot. Use `my-tenant.us.auth0.com`.
 - **Browser login redirects but the callback fails.** The
-  `https://<gateway-host>/oauth/callback` URL isn't on the **Allowed Callback
-  URLs** list for the Auth0 application.
+  `https://<gateway-host>/__zuplo/oauth/callback` URL isn't on the **Allowed
+  Callback URLs** list for the Auth0 application.
 - **Token endpoint returns `invalid_audience`.** The MCP client is reusing a
   token bound to a different route. Each gateway-issued token binds to one
   `operationId`; the client must obtain a separate token per route.

package/docs/mcp-gateway/auth/configuring-clerk.mdx

@@ -29,8 +29,8 @@ to MCP routes.
    then open **Configure → OAuth Applications**.
 2. Click **Add OAuth application**.
 3. Give the application a name (for example, `Zuplo MCP Gateway`).
-4. Set **Redirect URIs** to `https://<gateway-host>/oauth/callback`. Add
-   `http://localhost:9000/oauth/callback` for local development with
+4. Set **Redirect URIs** to `https://<gateway-host>/__zuplo/oauth/callback`. Add
+   `http://localhost:9000/__zuplo/oauth/callback` for local development with
    `zuplo dev`.
 5. Select the OIDC scopes the gateway needs — `openid`, `profile`, and `email`
    are enough.
@@ -143,8 +143,8 @@ endpoint with `curl` so you can see the raw responses.
 - **The policy rejects `frontendApiUrl` at boot.** The value includes a path,
   query string, or fragment. Use only the origin (`https://clerk.example.com`).
 - **Browser login redirects but the callback fails.** The
-  `https://<gateway-host>/oauth/callback` URL isn't on the OAuth application's
-  redirect URIs allow-list in Clerk.
+  `https://<gateway-host>/__zuplo/oauth/callback` URL isn't on the OAuth
+  application's redirect URIs allow-list in Clerk.
 
 ## Related
 

package/docs/mcp-gateway/auth/configuring-cognito.mdx

@@ -44,8 +44,9 @@ wrapper handles both.
 1. Under **App integration → App clients**, click **Create app client**.
 2. Choose **Confidential client**. The client must have a client secret — the
    gateway needs it for the federated token exchange.
-3. Set **Allowed callback URLs** to `https://<gateway-host>/oauth/callback`. Add
-   `http://localhost:9000/oauth/callback` for local development.
+3. Set **Allowed callback URLs** to
+   `https://<gateway-host>/__zuplo/oauth/callback`. Add
+   `http://localhost:9000/__zuplo/oauth/callback` for local development.
 4. Enable **Authorization code grant** under allowed OAuth flows.
 5. Enable the OIDC scopes the gateway needs — `openid`, `profile`, and `email`.
 6. Click **Create app client**.
@@ -115,8 +116,8 @@ endpoint with `curl` so you can see the raw responses.
   `https://`, a trailing slash, or an OAuth path. Strip those — use only
   `auth.example.com` or `my-pool.auth.us-east-1.amazoncognito.com`.
 - **Browser login lands on a Cognito error page.** The callback URL on the app
-  client doesn't match. Set it to `https://<gateway-host>/oauth/callback`
-  exactly.
+  client doesn't match. Set it to
+  `https://<gateway-host>/__zuplo/oauth/callback` exactly.
 - **`invalid_client` from Cognito's token endpoint.** The app client doesn't
   have a client secret, or the secret value doesn't match. Cognito confidential
   clients require both ID and secret.

package/docs/mcp-gateway/auth/configuring-entra.mdx

@@ -41,7 +41,7 @@ to MCP routes.
    directory only (single tenant)**. The wrapper does not support multi-tenant
    modes.
 4. Under **Redirect URI**, choose **Web** and set the value to
-   `https://<gateway-host>/oauth/callback`. Click **Register**.
+   `https://<gateway-host>/__zuplo/oauth/callback`. Click **Register**.
 5. On the application's **Overview** page, note the **Application (client) ID**
    and the **Directory (tenant) ID**. Both are UUIDs.
 
@@ -55,7 +55,8 @@ to MCP routes.
 ### Add the local development redirect URI
 
 1. Open **Authentication** on the application.
-2. Add `http://localhost:9000/oauth/callback` under **Web → Redirect URIs**.
+2. Add `http://localhost:9000/__zuplo/oauth/callback` under **Web → Redirect
+   URIs**.
 3. Save.
 
 ### Optional: restrict access
@@ -121,8 +122,8 @@ endpoint with `curl` so you can see the raw responses.
   verified domain, `common`, `organizations`, or `consumers`. Look up the tenant
   ID under **Overview** in the Entra admin center.
 - **`AADSTS50011` redirect URI mismatch.** The redirect URI on the app
-  registration doesn't match `https://<gateway-host>/oauth/callback` exactly.
-  Match scheme, host, and path.
+  registration doesn't match `https://<gateway-host>/__zuplo/oauth/callback`
+  exactly. Match scheme, host, and path.
 - **`AADSTS700016` application not found.** The client ID doesn't belong to the
   tenant the wrapper is configured with. Make sure `tenantId` and `clientId`
   come from the same app registration.

package/docs/mcp-gateway/auth/configuring-generic-oidc.mdx

@@ -53,8 +53,8 @@ at the same place:
 
 1. Create a new OIDC web application (or "regular web application", "OIDC
    client", "confidential client" — terminology varies).
-2. Set the **redirect URI** to `https://<gateway-host>/oauth/callback`. Add
-   `http://localhost:9000/oauth/callback` for local development with
+2. Set the **redirect URI** to `https://<gateway-host>/__zuplo/oauth/callback`.
+   Add `http://localhost:9000/__zuplo/oauth/callback` for local development with
    `zuplo dev`.
 3. Note the **client ID** and **client secret**.
 4. Restrict the application to the users or groups who should be able to
@@ -144,15 +144,15 @@ to the loopback dev-login endpoint:
       "jwksUrl": "http://localhost:9000/dev/jwks"
     },
     "browserLogin": {
-      "url": "http://127.0.0.1:9000/oauth/dev-login"
+      "url": "http://127.0.0.1:9000/__zuplo/oauth/dev-login"
     }
   }
 }
 ```
 
-When `browserLogin.url` points at `/oauth/dev-login`, you don't need `tokenUrl`,
-`clientId`, or `clientSecret`. The endpoint is only served on loopback origins;
-production deployments cannot reach it.
+When `browserLogin.url` points at `/__zuplo/oauth/dev-login`, you don't need
+`tokenUrl`, `clientId`, or `clientSecret`. The endpoint is only served on
+loopback origins; production deployments cannot reach it.
 
 See the [local development guide](../code-config/local-development.mdx) for the
 rest of the local setup.
@@ -166,7 +166,7 @@ rest of the local setup.
 | `oidc.issuer`                    | yes                | —                      | The OIDC issuer URL. Must include the scheme.                                                               |
 | `oidc.jwksUrl`                   | yes                | —                      | JWKS endpoint that publishes the IdP's signing keys.                                                        |
 | `oidc.audience`                  | no                 | unset                  | Optional ID-token audience override. Leave unset when ID tokens use the OIDC `client_id` as their audience. |
-| `browserLogin.url`               | yes                | —                      | The IdP's `/authorize` endpoint. The loopback `/oauth/dev-login` shortcut works for local dev.              |
+| `browserLogin.url`               | yes                | —                      | The IdP's `/authorize` endpoint. The loopback `/__zuplo/oauth/dev-login` shortcut works for local dev.      |
 | `browserLogin.tokenUrl`          | for federated OIDC | —                      | The IdP's token endpoint. Required for the federated authorization-code exchange.                           |
 | `browserLogin.clientId`          | for federated OIDC | —                      | OIDC client_id registered with the IdP.                                                                     |
 | `browserLogin.clientSecret`      | for federated OIDC | —                      | OIDC client_secret. Use `$env(...)`.                                                                        |
@@ -231,7 +231,7 @@ endpoint with `curl` so you can see the raw responses.
   is attached to the route in `routes.oas.json` and the `McpGatewayPlugin` is
   registered in `modules/zuplo.runtime.ts`.
 - **Browser login redirects but the callback fails.** The
-  `https://<gateway-host>/oauth/callback` URL isn't on the application's
+  `https://<gateway-host>/__zuplo/oauth/callback` URL isn't on the application's
   redirect URI allow-list at the IdP.
 
 ## Related

package/docs/mcp-gateway/auth/configuring-google.mdx

@@ -34,8 +34,8 @@ to MCP routes.
 3. Choose **Web application** as the application type.
 4. Give the client a name (for example, `Zuplo MCP Gateway`).
 5. Under **Authorized redirect URIs**, add
-   `https://<gateway-host>/oauth/callback`. Add
-   `http://localhost:9000/oauth/callback` for local development with
+   `https://<gateway-host>/__zuplo/oauth/callback`. Add
+   `http://localhost:9000/__zuplo/oauth/callback` for local development with
    `zuplo dev`.
 6. Click **Create**.
 
@@ -104,8 +104,8 @@ endpoint with `curl` so you can see the raw responses.
   Google's OAuth client ID shape — issuer URLs, API hostnames, project numbers.
   Use the full `123456789012-abc123def456.apps.googleusercontent.com` form.
 - **`redirect_uri_mismatch` from Google.** The redirect URI on the OAuth client
-  doesn't match `https://<gateway-host>/oauth/callback` exactly. Match scheme,
-  host, and path.
+  doesn't match `https://<gateway-host>/__zuplo/oauth/callback` exactly. Match
+  scheme, host, and path.
 - **`access_denied` for Google Workspace users.** The OAuth consent screen is
   set to **Internal** but the user belongs to a different workspace, or the user
   isn't on the **Test users** list during pre-verification.

package/docs/mcp-gateway/auth/configuring-keycloak.mdx

@@ -36,8 +36,9 @@ bind to MCP routes.
    roles** and **Direct access grants** — the gateway only needs the browser
    code flow.
 5. Click **Next**.
-6. Set **Valid redirect URIs** to `https://<gateway-host>/oauth/callback`. Add
-   `http://localhost:9000/oauth/callback` for local development.
+6. Set **Valid redirect URIs** to
+   `https://<gateway-host>/__zuplo/oauth/callback`. Add
+   `http://localhost:9000/__zuplo/oauth/callback` for local development.
 7. Set **Web origins** to `https://<gateway-host>` (and `http://localhost:9000`
    for local dev).
 8. Click **Save**.
@@ -113,7 +114,7 @@ endpoint with `curl` so you can see the raw responses.
 - **`keycloakBaseUrl` rejected at boot.** The value includes `/realms/...`.
   Strip the realm path; pass the realm name on the `realm` option instead.
 - **`Invalid redirect_uri` from Keycloak.** The callback URL on the client
-  doesn't match `https://<gateway-host>/oauth/callback`.
+  doesn't match `https://<gateway-host>/__zuplo/oauth/callback`.
 - **`Invalid client credentials`.** The client isn't a confidential client
   (Client authentication off), or the secret value doesn't match. Re-copy the
   secret from the **Credentials** tab.

package/docs/mcp-gateway/auth/configuring-logto.mdx

@@ -32,8 +32,8 @@ to MCP routes.
 3. Give the application a name (for example, `Zuplo MCP Gateway`) and click
    **Create application**.
 4. On the application's **Settings** tab, set **Redirect URIs** to
-   `https://<gateway-host>/oauth/callback`. Add
-   `http://localhost:9000/oauth/callback` for local development.
+   `https://<gateway-host>/__zuplo/oauth/callback`. Add
+   `http://localhost:9000/__zuplo/oauth/callback` for local development.
 5. Save.
 
 Note the **App ID** (= client ID) and **App secret** (= client secret) from the
@@ -106,8 +106,8 @@ endpoint with `curl` so you can see the raw responses.
   `/.well-known/openid-configuration`, or another path. Use the bare tenant
   endpoint origin.
 - **`redirect_uri` rejected by Logto.** The redirect URI on the application
-  doesn't match `https://<gateway-host>/oauth/callback`. Match scheme, host, and
-  path.
+  doesn't match `https://<gateway-host>/__zuplo/oauth/callback`. Match scheme,
+  host, and path.
 
 ## Related
 

package/docs/mcp-gateway/auth/configuring-okta.mdx

@@ -40,8 +40,8 @@ that bind to MCP routes. The Okta application you create represents the
    not need refresh tokens from Okta — it uses Okta only for browser identity,
    not as a long-running token source.
 5. Set **Sign-in redirect URIs** to your gateway's
-   `https://<gateway-host>/oauth/callback`. Add
-   `http://localhost:9000/oauth/callback` for local development with
+   `https://<gateway-host>/__zuplo/oauth/callback`. Add
+   `http://localhost:9000/__zuplo/oauth/callback` for local development with
    `zuplo dev`.
 6. Under **Assignments**, restrict access to the groups or users who should be
    able to authenticate against the gateway.
@@ -180,7 +180,7 @@ endpoint with `curl` so you can see the raw responses.
 - **"Invalid Okta domain" at boot.** `oktaDomain` includes a scheme prefix,
   trailing slash, or path. Use `acme.okta.com`.
 - **Browser login redirects but the callback fails.** The
-  `https://<gateway-host>/oauth/callback` URL isn't on the application's
+  `https://<gateway-host>/__zuplo/oauth/callback` URL isn't on the application's
   **Sign-in redirect URIs** allow-list in Okta.
 - **`invalid_audience` from the gateway's token endpoint.** The MCP client is
   reusing a token bound to a different route. Each gateway-issued token binds to

package/docs/mcp-gateway/auth/configuring-onelogin.mdx

@@ -31,8 +31,8 @@ bind to MCP routes.
 3. Give the application a display name (for example, `Zuplo MCP Gateway`) and
    click **Save**.
 4. Open the application's **Configuration** tab.
-5. Set **Redirect URIs** to `https://<gateway-host>/oauth/callback`. Add
-   `http://localhost:9000/oauth/callback` for local development.
+5. Set **Redirect URIs** to `https://<gateway-host>/__zuplo/oauth/callback`. Add
+   `http://localhost:9000/__zuplo/oauth/callback` for local development.
 6. Set **Login Url** to your gateway origin (`https://<gateway-host>`).
 7. Save.
 
@@ -111,7 +111,7 @@ endpoint with `curl` so you can see the raw responses.
 - **`oneLoginSubdomain` rejected at boot.** The value includes `https://`,
   `.onelogin.com`, or a trailing path. Pass only the subdomain (`acme`).
 - **`invalid_request: redirect_uri`.** The redirect URI on the OIDC application
-  doesn't match `https://<gateway-host>/oauth/callback`.
+  doesn't match `https://<gateway-host>/__zuplo/oauth/callback`.
 - **`invalid_client` from the token endpoint.** **Token Endpoint Authentication
   Method** isn't set to **POST** on the application's SSO tab.
 

package/docs/mcp-gateway/auth/configuring-ping.mdx

@@ -38,8 +38,8 @@ bind to MCP routes.
 2. Click **+ Add Application**, name it (for example, `Zuplo MCP Gateway`),
    choose **OIDC Web App** as the application type, and click **Save**.
 3. Open the application's **Configuration** tab.
-4. Set **Redirect URIs** to `https://<gateway-host>/oauth/callback`. Add
-   `http://localhost:9000/oauth/callback` for local development.
+4. Set **Redirect URIs** to `https://<gateway-host>/__zuplo/oauth/callback`. Add
+   `http://localhost:9000/__zuplo/oauth/callback` for local development.
 5. Set **Grant Types** to **Authorization Code**.
 6. Save.
 
@@ -144,7 +144,7 @@ endpoint with `curl` so you can see the raw responses.
 - **`environmentId` rejected at boot.** The wrapper expects a UUID. Don't pass
   the issuer URL, the auth domain, or the client ID.
 - **Browser login lands on a PingOne error page.** The redirect URI on the
-  application doesn't match `https://<gateway-host>/oauth/callback`.
+  application doesn't match `https://<gateway-host>/__zuplo/oauth/callback`.
 - **`invalid_client`.** The application is set to **Public** instead of
   **Confidential**. Confidential is required so the gateway can authenticate
   with the client secret.

package/docs/mcp-gateway/auth/configuring-workos.mdx

@@ -33,9 +33,9 @@ that bind to MCP routes.
 ### Add the redirect URI
 
 1. Open **Redirects** in the WorkOS Dashboard.
-2. Add `https://<gateway-host>/oauth/callback` as an allowed redirect URI. Add
-   `http://localhost:9000/oauth/callback` for local development with
-   `zuplo dev`.
+2. Add `https://<gateway-host>/__zuplo/oauth/callback` as an allowed redirect
+   URI. Add `http://localhost:9000/__zuplo/oauth/callback` for local development
+   with `zuplo dev`.
 3. Save.
 
 ### Note the API credentials
@@ -102,7 +102,8 @@ endpoint with `curl` so you can see the raw responses.
 ## Common issues
 
 - **`Invalid redirect URI`.** The redirect URI on **Redirects** in the WorkOS
-  Dashboard doesn't match `https://<gateway-host>/oauth/callback` exactly.
+  Dashboard doesn't match `https://<gateway-host>/__zuplo/oauth/callback`
+  exactly.
 - **`invalid_client`.** The client secret value doesn't match. WorkOS shows the
   secret only once after creation — regenerate it from **API Keys** if you've
   lost it.

package/docs/mcp-gateway/auth/manual-oauth-testing.mdx

@@ -108,10 +108,10 @@ REDIRECT_URI="http://localhost:8765/callback"
    ```json
    {
      "issuer": "https://gateway.example.com/mcp/linear-v1",
-     "authorization_endpoint": "https://gateway.example.com/oauth/authorize/mcp/linear-v1",
-     "token_endpoint": "https://gateway.example.com/oauth/token",
-     "registration_endpoint": "https://gateway.example.com/oauth/register",
-     "revocation_endpoint": "https://gateway.example.com/oauth/revoke",
+     "authorization_endpoint": "https://gateway.example.com/__zuplo/oauth/authorize/mcp/linear-v1",
+     "token_endpoint": "https://gateway.example.com/__zuplo/oauth/token",
+     "registration_endpoint": "https://gateway.example.com/__zuplo/oauth/register",
+     "revocation_endpoint": "https://gateway.example.com/__zuplo/oauth/revoke",
      "scopes_supported": ["mcp:tools"],
      "response_types_supported": ["code"],
      "grant_types_supported": ["authorization_code", "refresh_token"],
@@ -209,7 +209,7 @@ REDIRECT_URI="http://localhost:8765/callback"
    Open the URL in a browser. The flow is:
    1. The gateway redirects you to your IdP's login page.
    2. You authenticate at the IdP.
-   3. The IdP redirects back to the gateway's `/oauth/callback`.
+   3. The IdP redirects back to the gateway's `/__zuplo/oauth/callback`.
    4. The gateway renders the consent setup page.
    5. You click **Authorize**.
    6. The gateway redirects to your `redirect_uri` with `?code=...&state=...`.
@@ -231,8 +231,8 @@ REDIRECT_URI="http://localhost:8765/callback"
 
 1. **Exchange the code for tokens.**
 
-   `POST /oauth/token` with the authorization-code grant. Public clients send
-   `client_id` in the form body; confidential clients use HTTP Basic.
+   `POST /__zuplo/oauth/token` with the authorization-code grant. Public clients
+   send `client_id` in the form body; confidential clients use HTTP Basic.
 
    ```bash
    TOKEN_RESPONSE=$(curl -s -X POST "${TOKEN_ENDPOINT}" \
@@ -360,7 +360,7 @@ REDIRECT_URI="http://localhost:8765/callback"
    When you're done testing, revoke the grant.
 
    ```bash
-   curl -s -i -X POST "${GATEWAY}/oauth/revoke" \
+   curl -s -i -X POST "${GATEWAY}/__zuplo/oauth/revoke" \
      -H "content-type: application/x-www-form-urlencoded" \
      --data-urlencode "token=${NEW_REFRESH_TOKEN}" \
      --data-urlencode "token_type_hint=refresh_token" \

package/docs/mcp-gateway/auth/overview.mdx

@@ -45,8 +45,8 @@ OAuth flow:
   route.
 - An RFC 7591 Dynamic Client Registration endpoint.
 - An OAuth Client ID Metadata Document (CIMD) acceptor.
-- `/oauth/authorize`, `/oauth/token`, `/oauth/revoke`, and `/oauth/callback`
-  endpoints.
+- `/__zuplo/oauth/authorize`, `/__zuplo/oauth/token`, `/__zuplo/oauth/revoke`,
+  and `/__zuplo/oauth/callback` endpoints.
 
 Browser identity is delegated to an OIDC identity provider you configure —
 Auth0, Okta, or any OIDC discovery-compatible IdP. The IdP authenticates the
@@ -89,16 +89,16 @@ The gateway implements the following standards in their MCP-mandated subsets.
 | [RFC 8414 — Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414)                                          | Published at `/.well-known/oauth-authorization-server[/{routePath}]`.                                                                                                                                       |
 | [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html)                                         | Accepted alongside RFC 8414 as authorization-server discovery (added in the `2025-11-25` MCP revision).                                                                                                     |
 | [RFC 9728 — Protected Resource Metadata](https://datatracker.ietf.org/doc/html/rfc9728)                                            | Published at `/.well-known/oauth-protected-resource/{routePath}` per MCP route.                                                                                                                             |
-| [RFC 7591 — Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591)                                            | Accepted at `/oauth/register`.                                                                                                                                                                              |
+| [RFC 7591 — Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591)                                            | Accepted at `/__zuplo/oauth/register`.                                                                                                                                                                      |
 | [OAuth Client ID Metadata Documents (CIMD)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-00) | Recommended client identification path per the `2025-11-25` MCP revision. The gateway advertises `client_id_metadata_document_supported: true` and accepts URLs as `client_id` values when CIMD is enabled. |
 | [RFC 8707 — Resource Indicators](https://datatracker.ietf.org/doc/html/rfc8707)                                                    | MCP clients **MUST** include the `resource` parameter on every authorization and token request. The gateway validates that incoming bearer tokens were minted for the route's canonical resource URI.       |
 | [RFC 6750 — Bearer tokens](https://datatracker.ietf.org/doc/html/rfc6750)                                                          | `Authorization: Bearer ...` only, header position only — tokens in query strings are rejected.                                                                                                              |
-| [RFC 7009 — Token Revocation](https://datatracker.ietf.org/doc/html/rfc7009)                                                       | Published at `/oauth/revoke`.                                                                                                                                                                               |
+| [RFC 7009 — Token Revocation](https://datatracker.ietf.org/doc/html/rfc7009)                                                       | Published at `/__zuplo/oauth/revoke`.                                                                                                                                                                       |
 
 CIMD is the recommended client identification path going forward; DCR is
 retained for backwards compatibility with older MCP clients. Both work against
-the same `/oauth/register` and AS metadata surface — clients that support either
-are accommodated.
+the same `/__zuplo/oauth/register` and AS metadata surface — clients that
+support either are accommodated.
 
 ## Downstream flow
 
@@ -123,7 +123,7 @@ plus the MCP `resource` parameter binding.
 
 The flow is the standard MCP authorization handshake. The
 [`McpGatewayPlugin`](../code-config/overview.mdx) registers the
-`/.well-known/...` and `/oauth/...` endpoints automatically.
+`/.well-known/...` and `/__zuplo/oauth/...` endpoints automatically.
 
 ## Upstream flow
 
@@ -282,16 +282,16 @@ full URL catalog.
 | `/.well-known/oauth-authorization-server`             | GET       | RFC 8414 AS metadata (gateway-wide).                                           |
 | `/.well-known/oauth-authorization-server/{routePath}` | GET       | RFC 8414 AS metadata (per route, rebinds `issuer`).                            |
 | `/.well-known/oauth-protected-resource/{routePath}`   | GET       | RFC 9728 PRM (per route).                                                      |
-| `/oauth/register`                                     | POST      | RFC 7591 Dynamic Client Registration.                                          |
-| `/oauth/authorize`                                    | GET       | Gateway-wide authorize endpoint. Requires the `resource` parameter.            |
-| `/oauth/authorize/{routePath}`                        | GET       | Per-route authorize endpoint.                                                  |
-| `/oauth/callback`                                     | GET       | Browser-login callback from the IdP.                                           |
-| `/oauth/setup`                                        | GET, POST | Consent and multi-upstream connect page.                                       |
-| `/oauth/token`                                        | POST      | Token endpoint. Accepts `authorization_code` and `refresh_token` grants.       |
-| `/oauth/revoke`                                       | POST      | RFC 7009 revocation.                                                           |
-| `/.well-known/oauth-client/{connection}`              | GET       | OIDC Client ID Metadata Document for the upstream OAuth client (per upstream). |
-| `/auth/connections/{connection}/connect`              | GET       | Start the upstream OAuth flow.                                                 |
-| `/auth/connections/{connection}/callback`             | GET       | Upstream OAuth callback.                                                       |
+| `/__zuplo/oauth/register`                             | POST      | RFC 7591 Dynamic Client Registration.                                          |
+| `/__zuplo/oauth/authorize`                            | GET       | Gateway-wide authorize endpoint. Requires the `resource` parameter.            |
+| `/__zuplo/oauth/authorize/{routePath}`                | GET       | Per-route authorize endpoint.                                                  |
+| `/__zuplo/oauth/callback`                             | GET       | Browser-login callback from the IdP.                                           |
+| `/__zuplo/oauth/setup`                                | GET, POST | Consent and multi-upstream connect page.                                       |
+| `/__zuplo/oauth/token`                                | POST      | Token endpoint. Accepts `authorization_code` and `refresh_token` grants.       |
+| `/__zuplo/oauth/revoke`                               | POST      | RFC 7009 revocation.                                                           |
+| `/__zuplo/.well-known/oauth-client/{connection}`      | GET       | OIDC Client ID Metadata Document for the upstream OAuth client (per upstream). |
+| `/__zuplo/auth/connections/{connection}/connect`      | GET       | Start the upstream OAuth flow.                                                 |
+| `/__zuplo/auth/connections/{connection}/callback`     | GET       | Upstream OAuth callback.                                                       |
 
 The well-known metadata endpoints serve CORS-permissive responses
 (`Access-Control-Allow-Origin: *`) because browser-resident MCP clients fetch

package/docs/mcp-gateway/auth/upstream-oauth.mdx

@@ -77,9 +77,9 @@ can request tokens. The `clientRegistration` option controls how:
 - **CIMD with DCR fallback (`{ "mode": "auto" }`)** — the default. The gateway
   publishes a per-upstream
   [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-00)
-  at `/.well-known/oauth-client/{connection}?authProfileId=...` and tells the
-  upstream that URL is the client ID. If the upstream doesn't accept CIMD, the
-  gateway falls back to
+  at `/__zuplo/.well-known/oauth-client/{connection}?authProfileId=...` and
+  tells the upstream that URL is the client ID. If the upstream doesn't accept
+  CIMD, the gateway falls back to
   [RFC 7591 Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591).
   Auto mode requires nothing from the upstream provider beyond standard MCP
   authorization spec support and has no client secrets to rotate.
@@ -139,7 +139,7 @@ message; the user copies it into a browser.
 
 Each MCP route proxies to exactly one upstream, so the consent page typically
 shows one upstream to connect. The consent page is part of the gateway and
-renders automatically whenever a user lands at `/oauth/setup` mid-flow.
+renders automatically whenever a user lands at `/__zuplo/oauth/setup` mid-flow.
 
 ## Connect-required states
 
@@ -165,7 +165,7 @@ The full JSON-RPC error payload looks like:
       "state": "authenticating",
       "upstreamServerId": "linear",
       "operationId": "linear-mcp-server",
-      "authUrl": "https://gateway.example.com/auth/connections/linear/connect?browserTicket=eyJ...&operationId=linear-mcp-server",
+      "authUrl": "https://gateway.example.com/__zuplo/auth/connections/linear/connect?browserTicket=eyJ...&operationId=linear-mcp-server",
       "nextAction": "redirect",
       "authProfileId": "linear:user-oauth",
     },

package/docs/mcp-gateway/code-config/local-development.mdx

@@ -3,8 +3,9 @@ title: "Local development"
 sidebar_label: "Local development"
 description:
   Run the Zuplo MCP Gateway locally with zuplo dev, bypass your identity
-  provider with the loopback /oauth/dev-login shortcut, wire up an MCP client
-  against 127.0.0.1, and recover cleanly from the known workerd restart quirk.
+  provider with the loopback /__zuplo/oauth/dev-login shortcut, wire up an MCP
+  client against 127.0.0.1, and recover cleanly from the known workerd restart
+  quirk.
 ---
 
 The MCP Gateway runs the same way locally as any Zuplo project — `zuplo dev`,
@@ -44,7 +45,7 @@ When configuring an MCP client locally, use `127.0.0.1`:
 The same applies to any callback or redirect URI you configure with an identity
 provider for local testing.
 
-## Bypass your IdP with `/oauth/dev-login`
+## Bypass your IdP with `/__zuplo/oauth/dev-login`
 
 Setting up a real OIDC provider for local development is friction — you'd have
 to register a localhost callback, manage test users, and so on. The gateway
@@ -68,24 +69,24 @@ OAuth policy:
         "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",
       },
     },
   },
 }
 ```
 
-When `browserLogin.url` points at `/oauth/dev-login`, the
+When `browserLogin.url` points at `/__zuplo/oauth/dev-login`, the
 `browserLogin.tokenUrl`, `browserLogin.clientId`, and
 `browserLogin.clientSecret` options aren't required. The consent page renders
 normally.
 
 :::caution
 
-The `/oauth/dev-login` route returns `403 Forbidden` for any request that
-doesn't arrive over loopback. It's not a security risk to leave configured for
-production, but it's also not useful — production deployments should use a real
-OIDC provider through one of the
+The `/__zuplo/oauth/dev-login` route returns `403 Forbidden` for any request
+that doesn't arrive over loopback. It's not a security risk to leave configured
+for production, but it's also not useful — production deployments should use a
+real OIDC provider through one of the
 [IdP-specific wrappers](../auth/overview.mdx#identity-providers).
 
 :::
@@ -136,9 +137,10 @@ example, with Claude Desktop:
 ```
 
 The client triggers the gateway's OAuth flow on first connect. With
-`/oauth/dev-login` configured, the browser tab opens, lands on the consent page
-without any IdP login, and you connect each upstream through its normal browser
-OAuth flow. Subsequent calls reuse the issued tokens until they expire.
+`/__zuplo/oauth/dev-login` configured, the browser tab opens, lands on the
+consent page without any IdP login, and you connect each upstream through its
+normal browser OAuth flow. Subsequent calls reuse the issued tokens until they
+expire.
 
 See [Connect MCP clients](../connect-clients/overview.mdx) for client-specific
 snippets and the connect URL format.

package/docs/mcp-gateway/code-config/overview.mdx

@@ -31,9 +31,12 @@ export function runtimeInit(runtime: RuntimeExtensions) {
 ```
 
 The plugin registers the OAuth metadata, authorization endpoints, consent page,
-and upstream connect callbacks the gateway needs. It's a no-op when no
-MCP-related policy is present, so adding it to projects that don't yet use the
-gateway has zero runtime cost.
+and upstream connect callbacks the gateway needs. It also serves the read-only
+[MCP Server Registry](../server-registry.mdx) by default. See the
+[`McpGatewayPlugin` reference](../../programmable-api/mcp-gateway-plugin.mdx)
+for all configuration options. The plugin is a no-op when no MCP-related policy
+is present, so adding it to projects that don't yet use the gateway has zero
+runtime cost.
 
 ## 2. Define one OAuth policy
 
@@ -185,10 +188,12 @@ For a worked example with two upstreams and the full file layout, see
 
 - [`McpProxyHandler` reference](./mcp-proxy-handler.mdx) — every option and
   every behavior of the route handler.
+- [ZuploMcpSdk](../../programmable-api/mcp-sdk.mdx) — programmatically control
+  MCP tool results from custom handler modules.
 - [Compatibility dates](./compatibility-dates.mdx) — why `2026-03-01` is
   required and what older dates break.
 - [Local development](./local-development.mdx) — dev-loop, loopback URLs, the
-  `/oauth/dev-login` shortcut, and the `workerd` restart quirk.
+  `/__zuplo/oauth/dev-login` shortcut, and the `workerd` restart quirk.
 - [Add multiple upstream MCP servers](./multi-upstream.mdx) — one project, many
   upstream MCP servers.
 - [Curate the tools an upstream exposes](../how-to/curate-tools.mdx) — restrict