zuplo 6.70.53 → 6.70.55

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

@@ -0,0 +1,137 @@
+---
+title: "Connect MCP clients"
+sidebar_label: "Overview"
+description:
+  Learn how MCP clients connect to a Zuplo MCP Gateway, where to find the
+  connection URL, what the OAuth flow looks like on first use, and which clients
+  support which spec features.
+---
+
+The Zuplo MCP Gateway exposes each MCP route at a stable HTTPS URL that any
+modern MCP client can connect to. Clients speak the Streamable HTTP transport,
+complete an OAuth flow on first use, and then call tools, read resources, and
+run prompts through the gateway just as they would against any other remote MCP
+server.
+
+This page covers the connection model and links to a step-by-step guide for each
+of the major clients.
+
+## The MCP route URL
+
+Each MCP route in `config/routes.oas.json` is reachable at:
+
+```text
+https://{deploymentUrl}/{routePath}
+```
+
+The `{deploymentUrl}` is your project's deployment URL — for example
+`acme-mcp-main-abc123.d2.zuplo.dev` for a default Zuplo deployment, or a custom
+domain you configure for the project. The `{routePath}` is the path you set on
+the route in `routes.oas.json`. A typical convention is `/mcp/<provider>-v<n>`,
+so a Linear route looks like
+`https://acme-mcp-main-abc123.d2.zuplo.dev/mcp/linear-v1`.
+
+For local development with `zuplo dev`, the URL is
+`http://127.0.0.1:9000/{routePath}` — for example
+`http://127.0.0.1:9000/mcp/linear-v1`. See
+[Local development](../code-config/local-development.mdx).
+
+## Transport
+
+The gateway uses the **Streamable HTTP** transport defined in the MCP
+specification. Clients POST JSON-RPC requests to the MCP route URL. The gateway
+does not currently accept GET requests for server-sent event streams — it
+returns `405 Method Not Allowed` — so configure your client to use Streamable
+HTTP, not the older two-endpoint HTTP+SSE transport.
+
+For more on transports, see the
+[MCP transports specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports).
+
+## What happens on first connect
+
+The first time a user connects, the gateway runs two distinct OAuth handshakes
+before any tool call reaches an upstream MCP server.
+
+1. **Discovery.** The client POSTs an MCP request to the route URL without an
+   `Authorization` header. The gateway responds with `401 Unauthorized` and a
+   `WWW-Authenticate` header that points at the gateway's
+   [Protected Resource Metadata document (RFC 9728)](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization).
+2. **Gateway login.** The client opens the gateway's authorization endpoint in a
+   browser. The gateway redirects the user to your identity provider — Auth0,
+   Okta, Entra, Google, Cognito, or any of the other
+   [supported IdPs](../auth/overview.mdx#identity-providers) — to sign in. After
+   login, the gateway issues an access token bound to the route URL and returns
+   it to the client through the standard OAuth 2.1 Authorization Code with PKCE
+   flow.
+3. **Upstream consent.** If the route's upstream MCP server requires per-user
+   OAuth (Linear, Notion, Stripe, GitHub, and so on), the gateway shows a
+   consent page with a **Connect** button for the upstream. Clicking **Connect**
+   opens the upstream provider's OAuth flow in the same browser. Once the
+   upstream is connected, the user clicks **Authorize** and the gateway returns
+   the access token to the client.
+
+After the first connect, subsequent requests reuse the issued access token and
+the stored upstream credentials. Tokens refresh automatically. If the gateway
+needs the user to re-consent to an upstream — for example, when an upstream
+provider revokes the gateway's credentials — the client receives a JSON-RPC
+error with a URL to open in the browser to complete re-consent.
+
+For the full authentication model, see
+[Authentication overview](../auth/overview.mdx).
+
+## Client compatibility
+
+The table below summarizes which MCP spec features each major client supports
+today. All clients listed here support remote Streamable HTTP and work with the
+Zuplo MCP Gateway.
+
+| Client                                                               | Tools | Prompts | Resources | Roots | Sampling | Elicitation | DCR | CIMD | Apps |
+| -------------------------------------------------------------------- | :---: | :-----: | :-------: | :---: | :------: | :---------: | :-: | :--: | :--: |
+| [Claude Desktop](./claude-desktop.mdx)                               |  yes  |   yes   |    yes    |  yes  |    –     |      –      | yes |  –   | yes  |
+| [Claude.ai (web)](./claude-desktop.mdx)                              |  yes  |   yes   |    yes    |   –   |    –     |      –      | yes | yes  | yes  |
+| [Claude Code](./claude-code.mdx)                                     |  yes  |   yes   |    yes    |  yes  |    –     |     yes     | yes |  –   |  –   |
+| [ChatGPT](./chatgpt.mdx)                                             |  yes  |    –    |     –     |   –   |    –     |      –      | yes | yes  | yes  |
+| [Cursor](./cursor.mdx)                                               |  yes  |   yes   |     –     |  yes  |    –     |     yes     | yes |  –   | yes  |
+| [VS Code (GitHub Copilot)](./vs-code.mdx)                            |  yes  |   yes   |    yes    |  yes  |   yes    |     yes     | yes | yes  | yes  |
+| [Windsurf (Cascade)](./other-clients.mdx#windsurf)                   |  yes  |    –    |     –     |   –   |    –     |      –      | yes |  –   |  –   |
+| [Goose](./other-clients.mdx#goose)                                   |  yes  |   yes   |    yes    |  yes  |   yes    |     yes     | yes |  –   | yes  |
+| [Gemini CLI](./other-clients.mdx#gemini-cli)                         |  yes  |   yes   |     –     |   –   |    –     |      –      | yes |  –   |  –   |
+| [GitHub Copilot CLI](./other-clients.mdx#github-copilot-cli)         |  yes  |    –    |     –     |   –   |   yes    |     yes     | yes |  –   |  –   |
+| [Postman](./other-clients.mdx#postman)                               |  yes  |   yes   |    yes    |   –   |   yes    |     yes     |  –  |  –   | yes  |
+| [MCPJam](./other-clients.mdx#mcpjam)                                 |  yes  |   yes   |    yes    |   –   |    –     |     yes     | yes | yes  | yes  |
+| [Continue](./other-clients.mdx#continue)                             |  yes  |   yes   |    yes    |   –   |    –     |      –      |  –  |  –   | yes  |
+| [LibreChat](./other-clients.mdx#librechat)                           |  yes  |    –    |     –     |   –   |    –     |      –      | yes |  –   |  –   |
+| [JetBrains AI Assistant](./other-clients.mdx#jetbrains-ai-assistant) |  yes  |    –    |     –     |   –   |    –     |      –      |  –  |  –   |  –   |
+
+Capability data is sourced from the
+[official MCP clients page](https://modelcontextprotocol.io/clients). Clients
+ship new features frequently; check the client's own documentation for the
+latest support status.
+
+:::note
+
+The gateway exposes whatever capabilities the upstream MCP servers expose. If an
+upstream server only ships tools, a client that supports resources won't see
+anything in `resources/list` for that server. The compatibility matrix above
+tracks **what each client can consume**, not what the gateway forwards.
+
+:::
+
+## Per-client guides
+
+- [Claude Desktop](./claude-desktop.mdx) — add via `claude_desktop_config.json`.
+- [Claude Code](./claude-code.mdx) — add via the `claude mcp add` CLI command.
+- [ChatGPT](./chatgpt.mdx) — add via Settings → Connectors (Developer Mode
+  required).
+- [Cursor](./cursor.mdx) — add via `.cursor/mcp.json` or the one-click install
+  link.
+- [VS Code](./vs-code.mdx) — add via `.vscode/mcp.json` or the `code --add-mcp`
+  CLI command.
+- [Other clients](./other-clients.mdx) — Windsurf, Goose, Gemini CLI, GitHub
+  Copilot CLI, Postman, MCPJam, Continue, LibreChat, JetBrains AI Assistant.
+
+## Related
+
+- [How the MCP Gateway works](../how-it-works.mdx)
+- [Authentication overview](../auth/overview.mdx)
+- [Configuring the MCP Gateway with code](../code-config/overview.mdx)

package/docs/mcp-gateway/connect-clients/vs-code.mdx

@@ -0,0 +1,128 @@
+---
+title: "Connect VS Code (GitHub Copilot)"
+sidebar_label: "VS Code"
+description:
+  Connect VS Code with GitHub Copilot to a Zuplo MCP Gateway through
+  `.vscode/mcp.json`, the `code --add-mcp` CLI, or the Extensions view, and use
+  gateway tools in Copilot Chat's Agent mode.
+---
+
+VS Code with GitHub Copilot connects to remote MCP servers and exposes their
+tools to Copilot Chat's **Agent mode**. Add the Zuplo MCP Gateway through a
+`.vscode/mcp.json` file in your workspace, the `code` CLI, or the Extensions
+view.
+
+## Prerequisites
+
+- 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.
+- VS Code installed.
+- The GitHub Copilot extension installed and signed in.
+
+## Get the route URL
+
+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 gateway
+
+There are three supported ways to register the gateway.
+
+### Option 1: `.vscode/mcp.json` in your workspace
+
+Create or open `.vscode/mcp.json` at the root of your workspace, then add an
+HTTP server entry pointing at the route URL:
+
+```json title=".vscode/mcp.json"
+{
+  "servers": {
+    "zuplo": {
+      "type": "http",
+      "url": "https://{deploymentUrl}/{routePath}"
+    }
+  }
+}
+```
+
+Commit the file to source control to share the configuration with your team.
+
+### Option 2: `code --add-mcp` CLI
+
+Use the VS Code CLI to add a server to your user profile or to a workspace:
+
+```bash
+code --add-mcp '{"name":"zuplo","type":"http","url":"https://{deploymentUrl}/{routePath}"}'
+```
+
+VS Code prompts you to confirm the server registration and to choose between
+user-profile and workspace scope.
+
+### Option 3: Extensions view
+
+1. Open the **Extensions** view in VS Code.
+2. Type `@mcp` in the search field. VS Code shows the curated MCP server gallery
+   alongside any servers you've already registered.
+3. To add a custom server (the Zuplo gateway), use the **MCP: Add Server**
+   command from the Command Palette and paste your route URL when prompted, or
+   open **MCP: Open User Configuration** to edit `mcp.json` directly.
+
+## Authenticate
+
+The first time VS Code talks to the gateway, the gateway returns
+`401 Unauthorized` and VS Code opens the OAuth flow in your default browser.
+
+<Stepper>
+
+1. Sign in to the gateway with your identity provider.
+2. On the gateway's consent page, click **Connect** next to the upstream MCP
+   server and complete its OAuth flow.
+3. Click **Authorize** to finish. VS Code receives the access token and marks
+   the server as connected.
+
+</Stepper>
+
+Tokens refresh automatically. To revoke access, remove the server from
+`mcp.json` (or from MCP settings) and re-add it to start over.
+
+## Use tools in Copilot Chat
+
+Once the server is connected, open Copilot Chat and switch to **Agent** mode
+(the mode picker is at the top of the chat panel). Tools from the gateway appear
+in the tool picker — click the tools icon to see them and to enable or disable
+individual tools per chat. Reference resources from the gateway by typing `#` in
+your prompt.
+
+## What VS Code supports
+
+VS Code's MCP client is one of the most feature-complete on the market. With the
+Zuplo MCP Gateway it supports:
+
+- **Tools** — invoke gateway-exposed tools from Agent mode.
+- **Prompts** — surface prompts as slash commands.
+- **Resources** — reference resources with `#` in prompts.
+- **Roots** — declare workspace folders as roots.
+- **Sampling** — handle server-initiated sampling requests, including the
+  `tools` and `toolChoice` parameters added in MCP `2025-11-25`.
+- **Elicitation** — handle both form-mode and URL-mode elicitation requests,
+  including upstream re-authorization prompts.
+- **MCP Apps** — render interactive HTML widgets inline in the chat.
+- **DCR** and **CIMD** — both client registration paths are supported.
+
+## Troubleshooting
+
+- **Server stays in "Pending" state.** Confirm the URL in `mcp.json` is
+  reachable. VS Code shows server logs in the **Output** panel under **MCP** —
+  check there for the exact failure reason.
+- **Tools do not appear in Copilot Chat.** Confirm Copilot Chat is in **Agent**
+  mode. Tool calling is gated to that mode.
+- **OAuth flow does not start.** Some corporate proxies block the local
+  callback. Try connecting from outside the proxy or use the VS Code setting to
+  override the callback port.
+
+## Related
+
+- [Connect MCP clients overview](./overview.mdx)
+- VS Code's docs:
+  [Add and manage MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)
+- [Authentication overview](../auth/overview.mdx)

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

@@ -0,0 +1,266 @@
+---
+title: "How the MCP Gateway works"
+sidebar_label: "How it works"
+description:
+  Architecture overview — request lifecycle, the two OAuth surfaces, the
+  Streamable HTTP transport, and the configuration model.
+---
+
+The MCP Gateway is a set of policies and a route handler that run inside any
+Zuplo project. A single deployment hosts any number of public MCP routes, each
+pointing at a different upstream MCP server. The gateway runs its own OAuth 2.1
+authorization server for inbound clients and acts as an OAuth client to each
+upstream provider.
+
+## Request lifecycle
+
+The diagram below shows a first-time call from an MCP client to a route that
+wires a single OAuth-protected upstream. Once tokens are issued and the upstream
+connection exists, the gateway skips the OAuth dance and goes straight from the
+bearer-token check to the upstream proxy.
+
+<Diagram height="h-72">
+  <DiagramNode id="client">MCP Client</DiagramNode>
+  <DiagramGroup id="gateway" label="Zuplo MCP Gateway">
+    <DiagramNode id="oauth" variant="zuplo">
+      OAuth endpoints
+    </DiagramNode>
+    <DiagramNode id="route" variant="zuplo">
+      MCP route
+    </DiagramNode>
+  </DiagramGroup>
+  <DiagramNode id="idp">Identity Provider</DiagramNode>
+  <DiagramNode id="upstream">Upstream MCP Server</DiagramNode>
+  <DiagramEdge from="client" to="oauth" label="Discover + auth" />
+  <DiagramEdge from="oauth" to="idp" label="Browser login" />
+  <DiagramEdge from="client" to="route" label="Bearer token" />
+  <DiagramEdge from="route" to="upstream" label="Proxied request" />
+</Diagram>
+
+The flow in detail, for the first call from a new client to an OAuth-protected
+upstream:
+
+1. The client POSTs to the MCP route with no token.
+2. The gateway returns `401` with
+   `WWW-Authenticate: Bearer resource_metadata=...`.
+3. The client fetches the Protected Resource Metadata document and discovers the
+   gateway's authorization server.
+4. The client fetches the AS metadata, registers via DCR (or uses a CIMD client
+   ID), and starts the authorization flow with PKCE and a `resource` parameter.
+5. The gateway redirects the user's browser to the configured identity provider
+   for login.
+6. After login, the gateway renders a consent page that lists every upstream the
+   route requires.
+7. The user completes upstream OAuth for each required upstream — the gateway
+   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`.
+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.
+
+Once tokens are issued and the upstream connection exists, only step 10 runs on
+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 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
+  requests reuse the stored credential. If an upstream returns a 401 mid-call,
+  the gateway refreshes and retries once before propagating the error.
+
+## Two OAuth surfaces
+
+The gateway plays two OAuth roles simultaneously. The inbound role — as an OAuth
+server for MCP clients — and the outbound role — as an OAuth client to each
+upstream — use different policies and different credential stores.
+
+### Downstream — gateway as OAuth 2.1 server
+
+The gateway implements the MCP authorization spec from the perspective of a
+Resource Server and an Authorization Server. MCP clients talk OAuth to the
+gateway, not to the upstream providers. Standards observed:
+
+- **RFC 8414** Authorization Server Metadata and **OpenID Connect Discovery
+  1.0** for AS discovery.
+- **RFC 9728** Protected Resource Metadata for advertising the AS.
+- **RFC 7591** Dynamic Client Registration and **OAuth Client ID Metadata
+  Documents** (CIMD) for client registration. CIMD is the recommended path; DCR
+  is supported for clients that don't speak it.
+- **RFC 7636** PKCE with S256 required.
+- **RFC 8707** Resource Indicators — the `resource` parameter is required on
+  every authorization and token request.
+- **RFC 6750** Bearer tokens — the gateway issues opaque tokens carried in
+  `Authorization: Bearer` headers.
+
+The gateway delegates user authentication to a configured OIDC identity provider
+(Auth0 through `McpAuth0OAuthInboundPolicy` or generic OIDC through
+`McpOAuthInboundPolicy`). The provider's tokens never leave the gateway — the
+gateway issues its own opaque access tokens, scoped to `mcp:tools`, and binds
+each to one specific MCP route. The route binding is a deliberate blast-radius
+constraint: a token issued for `/mcp/linear-v1` can't be replayed against
+`/mcp/stripe-v1`, so a stolen token from one upstream stays confined to that
+upstream.
+
+Token passthrough is explicitly forbidden by the spec, and the gateway enforces
+it: inbound auth headers don't leak to the upstream.
+
+### Upstream — gateway as OAuth client
+
+For each upstream MCP server that requires OAuth, the gateway acts as a standard
+OAuth client.
+
+- **Per-user OAuth (`authMode: "user-oauth"`)** — every end user goes through a
+  one-time consent. The gateway stores their access and refresh tokens encrypted
+  at rest, keyed by user. Token refresh is automatic.
+- **Shared OAuth (`authMode: "shared-oauth"`)** — one upstream connection shared
+  across every user of the gateway. The connection is established by an
+  administrator through a special connect flow.
+
+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.
+- `clientRegistration: { mode: "manual" }` — supply a pre-registered `clientId`
+  and `clientSecret` (and optional auth method).
+
+When the gateway needs an upstream connection it doesn't have yet, the gateway
+returns a JSON-RPC error with a URL to open in a browser. Modern MCP clients pop
+the browser automatically; older ones surface the URL for the user to open
+manually.
+
+## Transport — Streamable HTTP, POST only
+
+Every MCP route uses the
+[Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports)
+defined in the MCP spec. The gateway accepts POST requests only:
+
+- `POST` on the route path carries the JSON-RPC payload.
+- `GET` on the same path returns `405 Method Not Allowed` with `Allow: POST`.
+  The gateway doesn't open SSE streams for server-initiated messages.
+
+Route paths are whatever you set in `routes.oas.json` — `/mcp/<provider>-v<n>`
+is the recommended convention (and what the dogfood gateway uses), but any path
+the OpenAPI router accepts works.
+
+The gateway is **stateless**. It does not maintain MCP sessions, doesn't track
+subscriptions, and doesn't emit server-initiated notifications. Statelessness is
+what lets the gateway run on Zuplo's edge runtime and scale horizontally without
+session affinity — any node can serve any request. Stateful MCP features
+(long-running subscriptions, server-initiated sampling) aren't supported through
+the gateway today.
+
+## Configuration model
+
+The MCP Gateway is configured the same way as the rest of a Zuplo project: an
+OpenAPI route file, a policy library, and a runtime plugin registration. Every
+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.                                                                                                                                                                                                   |
+| 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.                                                                                                                                                                                                                       |
+| One route per upstream                               | `config/routes.oas.json`   | Uses `McpProxyHandler` with the upstream URL as `rewritePattern`. Attaches the OAuth policy + token exchange policy.                                                                                                                                                                                   |
+
+A minimal route looks like this:
+
+```jsonc title="config/routes.oas.json"
+"/mcp/linear-v1": {
+  "get,post": {
+    "operationId": "linear-mcp-server",
+    "x-zuplo-route": {
+      "corsPolicy": "none",
+      "handler": {
+        "module": "$import(@zuplo/runtime/mcp-gateway)",
+        "export": "McpProxyHandler",
+        "options": { "rewritePattern": "https://mcp.linear.app/mcp" }
+      },
+      "policies": {
+        "inbound": ["auth0-managed-oauth", "mcp-token-exchange-linear"]
+      }
+    }
+  }
+}
+```
+
+The plugin registration:
+
+```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 `operationId` on each MCP route is more than a label — it identifies the MCP
+route and is the `virtualServerName` in analytics. Changing it strands all
+stored tokens and per-user upstream connections.
+
+:::caution
+
+MCP Gateway features require `compatibilityDate >= 2026-03-01` in `zuplo.jsonc`.
+See [Compatibility dates](./code-config/compatibility-dates.mdx).
+
+:::
+
+### Inbound policy chain
+
+For each request to an MCP route, the policies run in this order:
+
+1. **MCP OAuth policy** — one of the
+   [IdP-specific wrappers](./auth/overview.mdx#identity-providers)
+   (`mcp-auth0-oauth-inbound`, `mcp-okta-oauth-inbound`,
+   `mcp-entra-oauth-inbound`, and so on) or the generic `mcp-oauth-inbound`.
+   Validates the gateway-issued bearer token, asserts audience binding and
+   scope.
+2. **MCP token-exchange policy** (`mcp-token-exchange-inbound`) — resolves the
+   right upstream credential for the authenticated user. If the user hasn't
+   connected this upstream yet, the policy returns a connect-required error.
+3. **Capability filter policy** (`mcp-capability-filter-inbound`, optional) —
+   filters the upstream's `tools/list`, `prompts/list`, `resources/list`, and
+   `resources/templates/list` responses, and blocks calls to hidden capabilities
+   with `MethodNotFound`.
+
+The handler — `McpProxyHandler` — runs after the policies, forwards the request
+to the upstream URL, and emits capability analytics events.
+
+## What the gateway does not do
+
+A few capabilities are intentionally out of scope, at least today:
+
+- **No stateful sessions.** The gateway doesn't open SSE streams, doesn't track
+  `MCP-Session-Id`, and doesn't proxy server-initiated requests.
+- **No `tools/list` caching.** Every request goes upstream. If an upstream is
+  slow to list capabilities, callers feel it.
+- **No prompt-injection or PII scanning at the policy level.** These belong in a
+  separate inbound policy and can be composed alongside the MCP policies through
+  Zuplo's standard policy model.
+- **No rate limiting on OAuth endpoints out of the box.** Add Zuplo's built-in
+  `rate-limit-inbound` policy to those routes if needed.
+
+## Related
+
+- [Set up an MCP Gateway](./code-config/overview.mdx) — the how-to that puts
+  this conceptual model into practice.
+- [Quickstart](./quickstart.mdx) — add the MCP Gateway plugin to a Zuplo project
+  and front your first upstream.
+- [Authentication overview](./auth/overview.mdx) — the two OAuth layers expanded
+  with the full standards table.
+- [Reference](./reference.mdx) — the full URL catalog, default TTLs,
+  compatibility date, and OAuth metadata extensions.
+- [Troubleshooting](./troubleshooting.mdx) — the gotchas that catch most people
+  the first time.