zuplo 7.4.4 → 7.4.6

package/docs/mcp-gateway/connect-clients/chatgpt.mdx

@@ -2,22 +2,28 @@
 title: "Connect ChatGPT"
 sidebar_label: "ChatGPT"
 description:
-  Connect ChatGPT to a Zuplo MCP Gateway as a custom connector using Developer
-  Mode, complete the OAuth flow, and start using your tools in conversation.
+  Connect ChatGPT to a Zuplo MCP Gateway as a custom app using Developer Mode,
+  scan the gateway tools, complete the OAuth flow, and use the app in
+  conversation.
 ---
 
-ChatGPT connects to remote MCP servers as **custom connectors**. To add a custom
-connector that exposes general-purpose MCP tools, you need to enable **Developer
-Mode** on your ChatGPT account. Once enabled, paste the gateway URL into
-ChatGPT's connector settings and complete the OAuth flow.
+ChatGPT connects to remote MCP servers as **custom apps**. OpenAI previously
+called these "custom connectors", and some ChatGPT screens still use connector
+language, but the current ChatGPT docs use **apps** as the primary term.
+
+To add a Zuplo MCP Gateway route to ChatGPT, enable **Developer Mode**, create
+an app that points at the gateway's public MCP route URL, scan the tools, and
+complete the OAuth flow.
 
 :::note
 
-ChatGPT's general-purpose custom-connector support runs through Developer Mode,
-which is available on Pro, Team, Enterprise, and Edu plans. Before Developer
-Mode shipped, connector support in ChatGPT was limited to read-only Deep
-Research connectors. Use Developer Mode to expose the full range of tools the
-Zuplo MCP Gateway provides.
+OpenAI's current ChatGPT docs describe full MCP app support, including
+write/modify actions, as a beta for ChatGPT Business, Enterprise, and Edu plans
+on ChatGPT web. Pro users can connect MCP servers with read/fetch permissions in
+Developer Mode, but full MCP support is not currently available to Pro users.
+Check OpenAI's
+[Developer mode and MCP apps in ChatGPT](https://help.openai.com/en/articles/12584461-developer-mode-apps-and-full-mcp-connectors-in-chatgpt-beta)
+article for the latest plan availability.
 
 :::
 
@@ -25,12 +31,20 @@ Zuplo MCP Gateway provides.
 
 - A Zuplo project with the MCP Gateway plugin configured and at least one MCP
   route. See the [quickstart](../quickstart.mdx) if you haven't set one up yet.
-- A ChatGPT Pro, Team, Enterprise, or Edu subscription.
-- Developer Mode enabled on your ChatGPT account. The toggle lives in
-  **Settings** → **Connectors** → **Advanced** (the exact location varies by
-  plan; see OpenAI's
-  [Apps SDK documentation](https://developers.openai.com/apps-sdk/) for current
-  instructions).
+- A ChatGPT Business, Enterprise, or Edu workspace for full MCP apps. Pro users
+  can use read/fetch MCP servers only.
+- Developer Mode enabled for the ChatGPT account or workspace. OpenAI's current
+  Apps SDK guide says to enable it from **Settings** → **Apps & Connectors** →
+  **Advanced settings**. Business and Enterprise/Edu workspaces may require an
+  admin or owner to enable Developer Mode first from workspace settings.
+- A public HTTPS MCP route URL. ChatGPT does not connect directly to localhost
+  or private-network MCP servers. For local or private development, use OpenAI's
+  [Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnel)
+  or another HTTPS tunnel.
+- If your gateway uses OAuth, the identity provider should support the MCP
+  authorization requirements ChatGPT expects. For long-lived connections, verify
+  that your provider can issue refresh tokens; OpenAI recommends advertising and
+  requesting the `offline_access` scope when using OpenID Connect.
 
 ## Get the route URL
 
@@ -38,58 +52,89 @@ Each MCP route in `config/routes.oas.json` is reachable at
 `https://{deploymentUrl}/{routePath}` once deployed — for example
 `https://{deploymentUrl}/mcp/linear-v1`.
 
-## Add the connector
+## Add the app
 
 <Stepper>
 
-1. **Open Connectors settings in ChatGPT.**
+1. **Enable Developer Mode.**
+
+   In ChatGPT web, open **Settings** → **Apps & Connectors** → **Advanced
+   settings** and enable **Developer Mode**. In Business, Enterprise, or Edu
+   workspaces, an admin or owner may need to enable Developer Mode from
+   workspace settings first. See OpenAI's
+   [Developer mode and MCP apps in ChatGPT](https://help.openai.com/en/articles/12584461-developer-mode-apps-and-full-mcp-connectors-in-chatgpt-beta)
+   article for the current plan-specific path.
+
+2. **Create an app.**
+
+   Open **Settings** → **Apps & Connectors** and click **Create**. In some
+   workspaces, the create flow is under **Workspace settings** → **Apps** →
+   **Create**.
 
-   In the ChatGPT web app, open **Settings** → **Connectors**.
+3. **Enter the gateway app details.**
 
-2. **Add a custom connector.**
+   Provide a name, description, and the gateway route URL. Use the public MCP
+   route URL as the app or connector URL, for example
+   `https://{deploymentUrl}/mcp/linear-v1`.
 
-   Click the option to add a custom connector. Depending on your plan, this may
-   be **Add custom connector**, **Create**, or **Advanced** → **Add MCP
-   server**.
+4. **Choose the authentication method.**
 
-3. **Enter the gateway URL.**
+   If the gateway route is protected, choose OAuth or the OAuth/OpenID Connect
+   option in ChatGPT. The Zuplo gateway exposes the MCP OAuth metadata ChatGPT
+   needs for discovery.
 
-   Paste the route URL. Give the connector a name and description — these are
-   what ChatGPT shows in the conversation interface.
+5. **Scan the gateway tools.**
 
-4. **Authenticate against the gateway.**
+   Click **Scan Tools**. If ChatGPT opens an authorization prompt, complete the
+   gateway sign-in with the identity provider you configured for the route. Wait
+   for ChatGPT to finish scanning and show the tools exposed by the gateway.
 
-   Save the connector. ChatGPT opens the gateway's OAuth flow. Sign in with the
-   identity provider you configured for the gateway.
+6. **Complete the upstream connection.**
 
-5. **Complete the upstream connection.**
+   If the upstream MCP server also requires per-user OAuth, the gateway shows a
+   consent page with that upstream server. Click **Connect**, complete the
+   upstream OAuth flow, then click **Authorize** to return to ChatGPT.
 
-   The gateway shows a consent page with the upstream MCP server the route
-   proxies to. Click **Connect** next to the upstream, complete its OAuth flow,
-   then click **Authorize** to finish.
+7. **Create the app.**
 
-6. **Enable the connector for chats.**
+   Click **Create** after the scan succeeds. ChatGPT shows the app as a
+   Developer Mode app for your account, or as a draft app in workspace settings.
 
-   Back in ChatGPT, enable the connector for the conversations or assistants
-   where you want it active. Tools from the gateway then appear when ChatGPT
-   needs them.
+8. **Use the app in a chat.**
+
+   Start a new chat, click the **+** button near the message composer, choose
+   **More**, and select your app. Prompt ChatGPT with a request that should use
+   one of the gateway tools.
 
 </Stepper>
 
+## Publish for a workspace
+
+Developer Mode apps are private while you test them. To make the app available
+to a Business, Enterprise, or Edu workspace, an admin or owner must publish it
+from **Workspace settings** → **Apps**. OpenAI notes that workspace apps use a
+reviewed snapshot of the available tools; after changing the gateway's tools or
+tool schemas, refresh the app's actions in ChatGPT before publishing or
+republishing.
+
 ## What ChatGPT supports
 
-ChatGPT registers itself with the gateway through
-[Dynamic Client Registration (DCR)](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)
-and the newer
-[Client ID Metadata Documents (CIMD)](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)
-flow. It supports:
+ChatGPT acts as an MCP client for the gateway. For authenticated MCP servers,
+OpenAI's Apps SDK authentication guide says ChatGPT supports
+[Client ID Metadata Documents (CIMD)](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization),
+[Dynamic Client Registration (DCR)](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization),
+predefined OAuth clients, and Authorization Code with PKCE. The gateway handles
+the resource metadata and OAuth challenge flow for MCP clients.
+
+ChatGPT supports:
 
-- **Tools** — invoke gateway-exposed tools from the conversation.
-- **MCP Apps** — render interactive HTML widgets inline. This is the same
-  surface that powers the OpenAI Apps SDK, which is built directly on top of MCP
-  Apps.
+- **Tools** — invoke gateway-exposed tools from the conversation. Full MCP apps
+  no longer need to expose only `search` and `fetch` tools, though company
+  knowledge and deep research still use read/fetch-style access.
+- **MCP Apps** — render interactive HTML widgets inline through the OpenAI Apps
+  SDK conventions. The Apps SDK is built on top of MCP.
 
-ChatGPT doesn't currently consume prompts, resources, roots, sampling, or
+ChatGPT doesn't currently consume arbitrary MCP prompts, roots, sampling, or
 elicitation from a remote MCP server.
 
 ## Build an Apps SDK app on top of the gateway
@@ -107,21 +152,34 @@ For more background on Apps SDK and Zuplo-hosted MCP servers, see
 
 ## Troubleshooting
 
-- **"Custom connector" option isn't visible.** Confirm your plan supports
-  Developer Mode (Pro, Team, Enterprise, or Edu) and that Developer Mode is
-  enabled in your settings.
+- **Create or Developer Mode isn't visible.** Confirm your plan supports the
+  level of MCP access you need. Full MCP apps currently require ChatGPT
+  Business, Enterprise, or Edu. Your workspace admin may also need to enable
+  Developer Mode or grant access with RBAC.
 - **Sign-in succeeds but no tools appear.** Tools only appear when ChatGPT
   decides to invoke them. Try a prompt that mentions the action you want to
-  take. If the connector itself is disabled in a conversation, ChatGPT doesn't
-  see any of its tools.
+  take. If the app is not selected from the composer, ChatGPT doesn't see any of
+  its tools.
+- **Tool scan fails.** Confirm the MCP route is reachable over public HTTPS and
+  that the route returns the MCP OAuth metadata ChatGPT expects. Localhost and
+  private-network URLs require a tunnel.
 - **OAuth fails with a redirect error.** ChatGPT registers its redirect URI
-  dynamically. The gateway accepts dynamic registration by default. If you've
-  locked down DCR on your identity provider, switch to a provider that supports
-  DCR, or pre-register an OAuth app for ChatGPT.
+  through CIMD, DCR, or a predefined OAuth client, depending on how the app is
+  configured. If your identity provider blocks dynamic redirect URIs, use CIMD
+  or pre-register the redirect URL ChatGPT shows on the app management page.
+- **Users have to reauthenticate often.** Check whether your identity provider
+  issues refresh tokens. OpenAI's ChatGPT docs call out `offline_access` for
+  OpenID Connect providers.
 
 ## Related
 
 - [Connect MCP clients overview](./overview.mdx)
 - OpenAI's [Apps SDK documentation](https://developers.openai.com/apps-sdk/)
+- OpenAI's
+  [Connect from ChatGPT](https://developers.openai.com/apps-sdk/deploy/connect-chatgpt)
+  guide
+- OpenAI's
+  [Developer mode and MCP apps in ChatGPT](https://help.openai.com/en/articles/12584461-developer-mode-apps-and-full-mcp-connectors-in-chatgpt-beta)
+  article
 - [OpenAI Apps SDK with Zuplo](../../mcp-server/openai-apps-sdk.mdx)
 - [Authentication overview](../auth/overview.mdx)

package/docs/mcp-gateway/how-it-works.mdx

@@ -55,8 +55,8 @@ upstream:
    stores per-user tokens encrypted at rest.
 8. The user approves consent. The gateway redirects the client back with an
    authorization code.
-9. The client exchanges the code at `/oauth/token` and receives an access token
-   scoped to `mcp:tools`.
+9. The client exchanges the code at `/__zuplo/oauth/token` and receives an
+   access token scoped to `mcp:tools`.
 10. The client POSTs to the MCP route with the bearer token. The gateway
     validates the token, attaches the user's upstream credential, and proxies to
     the upstream MCP server.
@@ -66,9 +66,9 @@ subsequent calls.
 
 Three details that come up during debugging:
 
-- The `resource` parameter (RFC 8707) is required on `/oauth/authorize` and
-  `/oauth/token`. The gateway rejects tokens whose audience doesn't match the
-  route they're being used against.
+- The `resource` parameter (RFC 8707) is required on `/__zuplo/oauth/authorize`
+  and `/__zuplo/oauth/token`. The gateway rejects tokens whose audience doesn't
+  match the route they're being used against.
 - The consent screen lists the upstream the route depends on with a **Connect**
   button. The user can't approve the grant until the upstream is connected.
 - The upstream OAuth flow runs once per (user, upstream) pair. Subsequent
@@ -127,9 +127,9 @@ Client registration with the upstream supports two modes:
 
 - `clientRegistration: { mode: "auto" }` (the default) — the gateway publishes a
   per-upstream OAuth Client ID Metadata Document at
-  `/.well-known/oauth-client/<connection>` and tells the upstream that URL is
-  the `client_id`. If the upstream doesn't support CIMD, the gateway falls back
-  to RFC 7591 Dynamic Client Registration.
+  `/__zuplo/.well-known/oauth-client/<connection>` and tells the upstream that
+  URL is the `client_id`. If the upstream doesn't support CIMD, the gateway
+  falls back to RFC 7591 Dynamic Client Registration.
 - `clientRegistration: { mode: "manual" }` — supply a pre-registered `clientId`
   and `clientSecret` (and optional auth method).
 
@@ -168,7 +168,7 @@ project that uses the gateway has the same shape:
 | Piece                                                | Lives in                   | Purpose                                                                                                                                                                                                                                                                                                |
 | ---------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `compatibilityDate >= 2026-03-01`                    | `zuplo.jsonc`              | Unlocks MCP Gateway features. Required.                                                                                                                                                                                                                                                                |
-| `McpGatewayPlugin`                                   | `modules/zuplo.runtime.ts` | Registers the OAuth metadata, authorization endpoints, consent page, and upstream connect callbacks.                                                                                                                                                                                                   |
+| `McpGatewayPlugin`                                   | `modules/zuplo.runtime.ts` | Registers the OAuth metadata, authorization endpoints, consent page, upstream connect callbacks, and the [read-only MCP Server Registry](./server-registry.mdx). See [`McpGatewayPlugin` reference](../programmable-api/mcp-gateway-plugin.mdx) for all options.                                       |
 | One MCP OAuth policy                                 | `config/policies.json`     | Authenticates inbound MCP requests against your identity provider. One per project — pick the [wrapper for your IdP](./auth/overview.mdx#identity-providers) (Auth0, Cognito, Clerk, Entra, Google, Keycloak, Logto, Okta, OneLogin, Ping, WorkOS) or `mcp-oauth-inbound` for any other OIDC provider. |
 | One `mcp-token-exchange-inbound` policy per upstream | `config/policies.json`     | Resolves the user's upstream credential and attaches it as the upstream `Authorization` header. Omit for non-OAuth upstreams.                                                                                                                                                                          |
 | Optional `mcp-capability-filter-inbound` policy      | `config/policies.json`     | Curates the tools, prompts, resources, and resource templates the route exposes.                                                                                                                                                                                                                       |
@@ -262,5 +262,7 @@ A few capabilities are intentionally out of scope, at least today:
   with the full standards table.
 - [Reference](./reference.mdx) — the full URL catalog, default TTLs,
   compatibility date, and OAuth metadata extensions.
+- [Server Registry](./server-registry.mdx) — the read-only MCP Server Registry
+  API the gateway serves by default.
 - [Troubleshooting](./troubleshooting.mdx) — the gotchas that catch most people
   the first time.

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