zuplo 6.70.53 → 6.70.55

package/docs/mcp-gateway/capability-filtering.mdx

@@ -0,0 +1,162 @@
+---
+title: "Capability filtering"
+sidebar_label: "Capability filtering"
+description:
+  How the Zuplo MCP Gateway curates the tools, prompts, resources, and resource
+  templates an upstream MCP server exposes — what the
+  mcp-capability-filter-inbound policy filters, how projections work, and where
+  the boundary actually lives.
+---
+
+The Model Context Protocol lets a server advertise tools, prompts, resources,
+and resource templates. When the Zuplo MCP Gateway proxies an upstream server,
+every one of those capabilities flows through to the client by default. That's
+the right behavior when the upstream is small and trusted, and the wrong
+behavior when the upstream exposes dozens of operations only a few of which
+belong in front of an AI client.
+
+The `mcp-capability-filter-inbound` policy is how the gateway curates that
+surface area. This page covers what the policy filters, the rules that govern
+when capabilities are exposed versus hidden, the projection model that lets the
+gateway rewrite descriptions, and the boundary the filter actually enforces.
+
+To attach the policy to a route and walk through worked examples, see
+[Curate the tools an upstream exposes](./how-to/curate-tools.mdx).
+
+## What the policy filters
+
+The policy operates on four MCP capability types, each matched by the upstream
+identifier the protocol uses:
+
+| Capability          | Matched by    | List method                | Invocation method |
+| ------------------- | ------------- | -------------------------- | ----------------- |
+| `tools`             | `name`        | `tools/list`               | `tools/call`      |
+| `prompts`           | `name`        | `prompts/list`             | `prompts/get`     |
+| `resources`         | `uri`         | `resources/list`           | `resources/read`  |
+| `resourceTemplates` | `uriTemplate` | `resources/templates/list` | `resources/read`  |
+
+Matching is case-sensitive and exact. There's no regex, glob, or category
+matching — if the upstream returns a tool named `createUser` and the policy
+lists `create_user`, the tool stays hidden.
+
+## Omit versus empty array
+
+The behavior of each option depends on whether it's present at all:
+
+- **Omit the option** — every capability of that type passes through unchanged.
+  This is the default and is useful when filtering tools but leaving prompts and
+  resources alone.
+- **Provide an empty array** — expose nothing of that type. The list response
+  becomes empty and every direct call returns `MethodNotFound`.
+- **Provide entries** — expose only the listed items. Everything else is
+  filtered or blocked.
+
+The omit-versus-empty-array distinction is the single most consequential rule in
+the filter. Omitting an option is a pass-through; an empty array is the opposite
+— it hides every capability of that type. Confusing the two is the most common
+source of "why can the client still see that tool?" reports.
+
+## Projections
+
+Each allow-list entry is either a plain string (name only) or a projection
+object that keeps the upstream identifier but overrides what the client sees.
+Projections let the gateway rewrite the description for clarity, override tool
+annotations like `destructiveHint` or `readOnlyHint`, attach `_meta` fields that
+downstream middleware reads, or rewrite a resource's `name` and `mimeType` for a
+curated catalog.
+
+The upstream identifier — `name` for tools and prompts, `uri` for resources,
+`uriTemplate` for resource templates — is always required and serves as the
+stable match key. Annotation and `_meta` overrides are deep-merged with the
+upstream values: fields the projection specifies win, fields it doesn't specify
+pass through.
+
+Schema fields stay upstream. `inputSchema` and `outputSchema` always come from
+the upstream list response — the projection can't rewrite parameter shapes or
+enforce additional validation. A separate policy on the route handles those
+concerns when they come up.
+
+## How the filter behaves at runtime
+
+When the gateway sees a successful response to `tools/list`, `prompts/list`,
+`resources/list`, or `resources/templates/list`, it reads the list from the
+upstream response, keeps only items whose identifier appears on the allow-list,
+merges any projection overrides into the kept items, and returns the filtered
+list. Items the upstream returned that aren't on the allow-list are silently
+dropped — the client never learns they exist.
+
+When the gateway sees `tools/call`, `prompts/get`, or `resources/read`, it reads
+the target identifier from the request (`params.name` for tools and prompts,
+`params.uri` for resources). If the identifier isn't on the matching allow-list,
+the gateway returns a JSON-RPC `MethodNotFound` error **before forwarding
+upstream**:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "1",
+  "error": {
+    "code": -32601,
+    "message": "Method not found"
+  }
+}
+```
+
+The filter blocks calls before forwarding upstream, so a client that already
+knows a hidden tool's name — from a cached `tools/list`, a different gateway, or
+guesswork — still can't invoke it. The same block fires when the option is set
+to an empty array: every direct call of that capability type returns
+`MethodNotFound`.
+
+## Batch requests
+
+The policy handles JSON-RPC batch requests with two rules. List responses inside
+a batch are filtered per item — the policy matches each response item to its
+originating list request by ID and applies the same filtering and projection
+rules as for a single response. Hidden invocations inside a batch block the
+whole batch with a single `MethodNotFound` error; the gateway does not split,
+partially filter, or forward sibling items.
+
+## Where it sits in the policy chain
+
+The capability filter belongs **after** any policy that produces or replaces the
+upstream response — `mcp-token-exchange-inbound` is the most common one. The
+filter operates on the final response, so policies that transform the response
+upstream of it have already done their work by the time the filter runs.
+
+Keep the filter last in the chain even when there's no
+`mcp-token-exchange-inbound` policy on the route (for example, an API-key
+upstream via `set-headers-inbound` or `set-upstream-api-key-inbound`), so any
+future inbound policies that produce or replace responses run before it.
+
+## What the filter does not do
+
+A few capabilities are intentionally out of scope:
+
+- **No schema overrides.** `inputSchema` and `outputSchema` always come from the
+  upstream list response.
+- **No regex, glob, or category matching.** Allow-lists are exact, by
+  identifier. If the upstream renames a tool, the policy entry must be updated
+  to match.
+- **No non-JSON filtering.** Filtering applies only to JSON responses. Streamed
+  or binary responses pass through untouched.
+- **No effect on capability metadata in `initialize`.** The protocol-level
+  `serverCapabilities` block in the `initialize` response advertises which
+  capability types the server supports (tools, prompts, resources). The filter
+  doesn't strip those flags. A client sees that the gateway supports tools even
+  when the tool allow-list is empty; only the list and call responses change.
+- **No quota or rate limit.** Capability filtering trims the surface area the
+  gateway exposes but doesn't bound how often clients can call what remains.
+  Pair it with the [`rate-limit-inbound`](../policies/rate-limit-inbound.mdx)
+  policy when usage controls are needed.
+
+## Related
+
+- [Curate the tools an upstream exposes](./how-to/curate-tools.mdx) — how to
+  attach the policy, override descriptions, and verify the filter is active.
+- [`McpProxyHandler` reference](./code-config/mcp-proxy-handler.mdx) — the route
+  handler the filter runs in front of.
+- [Per-user OAuth to upstream MCP servers](./auth/upstream-oauth.mdx) — the
+  upstream side of the picture; the filter usually composes with the
+  token-exchange policy on the same route.
+- [MCP capability semantics in the specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools).

package/docs/mcp-gateway/code-config/compatibility-dates.mdx

@@ -0,0 +1,33 @@
+---
+title: "Compatibility dates"
+sidebar_label: "Compatibility dates"
+description:
+  The Zuplo MCP Gateway requires compatibilityDate 2026-03-01 or later in
+  zuplo.jsonc.
+---
+
+The Zuplo MCP Gateway requires `compatibilityDate >= 2026-03-01` in
+`zuplo.jsonc`.
+
+```jsonc
+// zuplo.jsonc
+{
+  "version": 1,
+  "compatibilityDate": "2026-03-01",
+}
+```
+
+:::caution
+
+The build fails if your project uses any MCP Gateway feature (the
+`McpProxyHandler` handler or an `mcp-*-inbound` policy) with a compatibility
+date older than `2026-03-01`. Bump the date in `zuplo.jsonc` before adding those
+features.
+
+:::
+
+New Zuplo projects default to a recent compatibility date, so this only applies
+to existing projects being upgraded to use the MCP Gateway.
+
+For background on Zuplo's compatibility-date system in general, see
+[Compatibility dates](../../programmable-api/compatibility-dates.mdx).

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

@@ -0,0 +1,198 @@
+---
+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.
+---
+
+The MCP Gateway runs the same way locally as any Zuplo project — `zuplo dev`,
+port `9000`, hot reload on file changes. A few details are specific to the
+gateway: the gateway prefers `127.0.0.1` over `localhost`, OAuth login can be
+short-circuited entirely in dev, and the local `workerd` worker needs a full
+restart after some MCP client connect attempts.
+
+## Start the gateway
+
+From the project root:
+
+```bash
+zuplo dev
+```
+
+The gateway listens at `http://127.0.0.1:9000`. Each MCP route in
+`routes.oas.json` becomes reachable at that origin — for example
+`http://127.0.0.1:9000/mcp/linear-v1`.
+
+## Prefer `127.0.0.1` over `localhost`
+
+OAuth metadata, callback URLs, and the in-dev login shortcut all key off the
+request origin. Other loopback aliases (`localhost`, `::1`, `[::1]`) can cause
+subtle OAuth issues in local dev.
+
+When configuring an MCP client locally, use `127.0.0.1`:
+
+```jsonc
+// Good
+"url": "http://127.0.0.1:9000/mcp/linear-v1"
+
+// Avoid in local dev — works for most things, breaks subtly for OAuth
+"url": "http://localhost:9000/mcp/linear-v1"
+```
+
+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`
+
+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
+exposes a loopback-only shortcut that skips the IdP round-trip entirely and
+signs you in as a fixed `dev-browser-user` subject.
+
+To use it, set `browserLogin.url` to the dev-login URL when configuring the
+OAuth policy:
+
+```jsonc
+// config/policies.json — using the generic mcp-oauth-inbound policy
+{
+  "name": "dev-oauth",
+  "policyType": "mcp-oauth-inbound",
+  "handler": {
+    "module": "$import(@zuplo/runtime/mcp-gateway)",
+    "export": "McpOAuthInboundPolicy",
+    "options": {
+      "oidc": {
+        "issuer": "http://127.0.0.1:9000",
+        "jwksUrl": "http://127.0.0.1:9000/.well-known/jwks.json",
+      },
+      "browserLogin": {
+        "url": "http://127.0.0.1:9000/oauth/dev-login",
+      },
+    },
+  },
+}
+```
+
+When `browserLogin.url` points at `/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
+[IdP-specific wrappers](../auth/overview.mdx#identity-providers).
+
+:::
+
+A common pattern is keeping two OAuth policies in the project — one for
+production (Auth0, Okta, Entra, or any other supported IdP) and one for local
+dev — and selecting between them in `routes.oas.json` based on the environment.
+
+## Environment variables
+
+When the OAuth policy reads from `$env(...)` references, define the values in a
+`.env` file at the project root:
+
+```bash
+# .env
+
+# Auth0 wrapper interpolations
+AUTH0_DOMAIN=your-tenant.us.auth0.com
+AUTH0_CLIENT_ID=your-auth0-web-app-client-id
+AUTH0_CLIENT_SECRET=your-auth0-web-app-client-secret
+
+# Optional: the audience the gateway requires on issued tokens
+AUTH0_AUDIENCE=https://mcp-gateway.example.com
+```
+
+`.env` is read at `zuplo dev` startup. Restart the dev server after adding or
+changing an environment variable.
+
+Never commit `.env` to source control. Instead, check in a `.env.example` (or
+`env.example`) that documents which variables are required and an
+empty/placeholder value for each.
+
+## Adding the gateway to a local MCP client
+
+Once `zuplo dev` is running and the route is reachable, add the gateway URL to
+your MCP client config the same way you'd add any other remote MCP server. For
+example, with Claude Desktop:
+
+```jsonc
+// claude_desktop_config.json
+{
+  "mcpServers": {
+    "linear-via-zuplo-local": {
+      "url": "http://127.0.0.1:9000/mcp/linear-v1",
+    },
+  },
+}
+```
+
+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.
+
+See [Connect MCP clients](../connect-clients/overview.mdx) for client-specific
+snippets and the connect URL format.
+
+## When `zuplo dev` crashes after a connect attempt
+
+Some MCP client connect attempts can leave the local dev server in a state where
+hot reload no longer recovers it. If the dev server stops responding after an
+MCP client connects — particularly after browser OAuth callbacks finish — fully
+restart `zuplo dev`:
+
+```bash
+# Stop zuplo dev with Ctrl+C
+# Start it again
+zuplo dev
+```
+
+Then have the MCP client reconnect. A restart doesn't force a re-consent — your
+upstream tokens are still stored.
+
+This is a known dev-only quirk and doesn't affect deployed gateways.
+
+## Verifying the gateway is up
+
+Two quick checks that don't require an MCP client:
+
+**Fetch the well-known OAuth metadata for a route.** The path follows the
+route's `operationId`:
+
+```bash
+curl http://127.0.0.1:9000/.well-known/oauth-protected-resource/mcp/linear-v1
+```
+
+A correct response is JSON with `resource`, `authorization_servers`,
+`bearer_methods_supported`, and `scopes_supported` fields.
+
+**Send a POST without a token.** The gateway should return `401` with a
+`WWW-Authenticate` header pointing at the Protected Resource Metadata URL:
+
+```bash
+curl -i -X POST http://127.0.0.1:9000/mcp/linear-v1 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+```
+
+If you see the 401 plus the challenge, the OAuth policy is wired up correctly.
+The next call from a real client will then start the OAuth dance.
+
+## Next steps
+
+- [`McpProxyHandler` reference](./mcp-proxy-handler.mdx) — the route handler the
+  gateway uses for proxying.
+- [Compatibility dates](./compatibility-dates.mdx) — pin `2026-03-01` in
+  `zuplo.jsonc`.
+- [Multi-upstream pattern](./multi-upstream.mdx) — one project, many upstreams.
+- [Connect MCP clients](../connect-clients/overview.mdx) — wire each client to
+  the local or deployed gateway URL.

package/docs/mcp-gateway/code-config/mcp-proxy-handler.mdx

@@ -0,0 +1,186 @@
+---
+title: "McpProxyHandler reference"
+sidebar_label: "McpProxyHandler"
+description:
+  The route handler that turns a Zuplo path into an MCP Gateway endpoint —
+  forwards POST requests to an upstream MCP server, rejects GET with 405, and
+  emits per-capability analytics on every call.
+---
+
+`McpProxyHandler` is the route handler that backs every MCP Gateway route. It
+accepts stateless Streamable HTTP requests over POST, forwards them to the
+configured upstream MCP server using Zuplo's standard URL rewrite, and emits a
+pair of analytics events per request so the gateway dashboard knows what each
+capability call did.
+
+## When to use it
+
+Use `McpProxyHandler` on any route that proxies to an upstream MCP server. Pair
+it with at least one MCP OAuth policy on the inbound chain; add an
+`mcp-token-exchange-inbound` policy when the upstream itself requires OAuth, and
+optionally `mcp-capability-filter-inbound` to curate what the upstream
+advertises.
+
+If the upstream uses a static API key or static header instead of OAuth, keep
+the MCP OAuth policy on the route, drop the token exchange policy, and add
+[`set-upstream-api-key-inbound`](../../policies/set-upstream-api-key-inbound.mdx)
+or [`set-headers-inbound`](../../policies/set-headers-inbound.mdx) to attach the
+credential before the handler forwards.
+
+## Configuration
+
+The handler is referenced from the route's `x-zuplo-route.handler` block in
+`routes.oas.json`:
+
+```jsonc
+"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"
+    ]
+  }
+}
+```
+
+Set `corsPolicy` to `"none"`. MCP clients aren't browser-based and shouldn't be
+sending ambient credentials.
+
+## Options
+
+### `rewritePattern` (required)
+
+The upstream MCP server URL. The handler forwards each authenticated POST to
+this URL, with the resolved upstream `Authorization: Bearer` header applied by
+the token exchange policy.
+
+Two value forms are supported:
+
+- **A literal HTTPS or HTTP URL.** Used verbatim as the upstream target.
+- **An environment-variable reference of the form `${env.X}`.** The variable
+  must resolve to a fully-qualified HTTP(S) URL.
+
+```jsonc
+// Literal URL
+{ "rewritePattern": "https://mcp.linear.app/mcp" }
+
+// Environment variable
+{ "rewritePattern": "${env.UPSTREAM_MCP_URL}" }
+```
+
+Dynamic request-based patterns are explicitly rejected — MCP routes need a
+stable upstream URL.
+
+:::caution
+
+The URL Rewrite handler's broader template syntax — `${params.x}`,
+`${headers.get("x")}`, and so on — is **not** supported on `rewritePattern` for
+MCP routes. Use a literal URL or an `${env.X}` reference.
+
+:::
+
+### `forwardSearch` (optional)
+
+Type: `boolean`. Default: `true`.
+
+When `true`, the inbound request's query string is appended to the upstream URL
+before forwarding. Set to `false` to drop client query parameters.
+
+### `followRedirects` (optional)
+
+Type: `boolean`. Default: `false`.
+
+When `false`, redirects from the upstream return as-is to the client (status
+code and `Location` header passed through). Set to `true` to have the runtime
+follow them transparently.
+
+### `mtlsCertificate` (optional)
+
+Type: `string`. The id of an mTLS certificate registered with the Zuplo project.
+When set, the upstream fetch uses mutual TLS with the specified client
+certificate. Most MCP upstreams don't require mTLS; leave this unset unless you
+specifically need it.
+
+## Behavior
+
+### GET returns 405
+
+The gateway only speaks stateless Streamable HTTP, and the MCP authorization
+spec uses POST for every JSON-RPC call. A `GET` to an MCP route returns:
+
+```http
+HTTP/1.1 405 Method Not Allowed
+Allow: POST
+Content-Type: application/problem+json
+
+{
+  "type": "https://httpproblems.com/http-status/405",
+  "status": 405,
+  "detail": "MCP Gateway routes support stateless Streamable HTTP requests over POST. Server-sent event GET streams are not supported."
+}
+```
+
+If you've seen an MCP server that exposes a GET endpoint for SSE event streams,
+that's a different transport. The Zuplo MCP Gateway is Streamable HTTP,
+POST-only.
+
+### POST forwards to the upstream
+
+A POST request runs through the inbound policy chain, then the handler emits
+capability analytics events, forwards to the upstream URL, and emits a
+completion event with `outcome`, `mcpStatus`, `latencyMs`, and any JSON-RPC
+error details.
+
+Inbound auth headers don't leak to the upstream — the gateway-issued bearer
+token is stripped, and the token exchange policy sets the upstream's own
+`Authorization: Bearer <upstream-token>` header.
+
+## Route requirements
+
+Every route that uses `McpProxyHandler` must:
+
+- **Set `operationId`.** It's used to identify the MCP route.
+- **Include an MCP OAuth policy** in the inbound chain — one of the
+  [IdP-specific wrappers](../auth/overview.mdx#identity-providers) (Auth0,
+  Cognito, Clerk, Entra, Google, Keycloak, Logto, Okta, OneLogin, Ping, WorkOS)
+  or the generic `mcp-oauth-inbound`.
+- **Include at most one `mcp-token-exchange-inbound` policy.**
+
+Across the project:
+
+- No two MCP routes can share an `operationId`.
+- No two MCP routes can share a path.
+- No two `mcp-token-exchange-*` policies can share an upstream `id`.
+
+## Analytics
+
+Every POST emits two analytics events when the request body parses as a JSON-RPC
+call:
+
+- A **`capability_invocation_started`** event fired before the upstream fetch,
+  carrying the parsed `mcpMethod` and `capabilityName`.
+- A **`capability_invocation_completed`** event fired after the response,
+  carrying `outcome`, `mcpStatus`, `latencyMs`, and any JSON-RPC error details.
+
+Each event also includes the route's `operationId` (as `virtualServerName`), the
+upstream `id` (as `upstreamServerName`), the authenticated `subjectId`, the
+`authProfileId`, and the `upstreamAuthMode`. See
+[Analytics](../observability/analytics.mdx) for the dashboard view and
+[Logging](../observability/logging.mdx) for the structured-log counterpart.
+
+## Related
+
+- `mcp-token-exchange-inbound` — resolves the upstream credential and handles
+  upstream 401 refresh and retry.
+- `mcp-capability-filter-inbound` — curates the upstream surface area on a
+  per-route basis.
+- [Multi-upstream pattern](./multi-upstream.mdx) — pair one `McpProxyHandler`
+  route with each upstream MCP server in one project.