zuplo 6.71.9 → 6.71.11

package/docs/articles/graphql.mdx

@@ -140,6 +140,7 @@ const config = {
     graphqlPlugin({
       schema: "./schema.graphql", // Also accepts a URL, e.g. https://...
       path: graphqlPath,
+      // endpoint: "/my-graphql", // Optional, defaults to "/graphql"
     }),
   ],
 };

package/docs/articles/securing-the-gateway-with-client-mtls.mdx

@@ -88,12 +88,26 @@ zuplo ca-certificate list --account your-account
 See the [`ca-certificate` CLI reference](../cli/ca-certificate-create.mdx) for
 all available subcommands (`create`, `list`, `describe`, `update`, `delete`).
 
-:::tip{title="Using an intermediate CA"}
+:::caution{title="Upload the self-signed root CA, not an intermediate"}
 
-If your client certificates are issued by an intermediate CA (rather than
-directly by your root), upload the root CA certificate that anchors the chain.
-Clients must send the leaf certificate plus any intermediate certificates when
-they connect.
+Zuplo must build a complete chain from the presented client certificate up to a
+trust anchor. Upload the **self-signed root** CA that anchors the chain — not an
+intermediate or subordinate CA. Uploading a subordinate CA is the most common
+cause of the `FAILED to get issuer certificate` error (see
+[Troubleshooting](#failed-to-get-issuer-certificate)).
+
+To confirm a certificate is a self-signed root, check that its subject and
+issuer are identical:
+
+```bash
+openssl x509 -in ca.pem -noout -subject -issuer -nameopt RFC2253
+```
+
+If `subject` and `issuer` match, it's a root. If they differ, the file is an
+intermediate CA — trace the chain to the root and upload that instead. When your
+client certificates are issued by an intermediate CA, clients still send the
+leaf certificate plus any intermediates when they connect (see
+[Test with curl](#4-test-with-curl)).
 
 :::
 
@@ -315,11 +329,73 @@ the policy in a working-copy or preview environment.
   `context.incomingRequestProperties.clientMtlsVerificationReason` to see why
   verification failed.
 
+### `FAILED to get issuer certificate`
+
+This error means Zuplo can't build a complete chain from the presented client
+certificate up to a trusted root. The usual cause is uploading an **intermediate
+or subordinate CA** instead of the **self-signed root** CA that anchors the
+chain.
+
+Confirm what you uploaded. A self-signed root has an identical subject and
+issuer:
+
+```bash
+openssl x509 -in ca.pem -noout -subject -issuer -nameopt RFC2253
+```
+
+If `subject` and `issuer` differ, the file is an intermediate CA. Find the root
+that anchors the chain and re-upload it:
+
+```bash
+# Remove the incorrect CA
+zuplo ca-certificate delete --cert-id mtlsca_abc123 --account your-account
+
+# Upload the self-signed root instead
+zuplo ca-certificate create --name my_ca --cert ./root-ca.pem --account your-account
+```
+
+If your CA is an Active Directory Certificate Services (AD CS) deployment,
+export the issuing CA's own certificate and inspect it:
+
+```bash
+# Export the CA certificate (often DER-encoded)
+certutil -ca.cert ca.cer
+
+# Convert DER to the PEM format Zuplo requires
+openssl x509 -inform der -in ca.cer -out ca.pem
+
+# Verify subject == issuer (a root); if not, export the root above it instead
+openssl x509 -in ca.pem -noout -subject -issuer -nameopt RFC2253
+```
+
+### `client certificate metadata not provided`
+
+The certificate verified at the edge, but the parsed certificate wasn't
+forwarded to your gateway workers, so `request.user.data.mtlsAuth` is empty even
+though the request was authenticated.
+
+The most common cause is an **oversized leaf client certificate**. Zuplo's edge
+can only forward client certificates up to roughly 10 KB of DER-encoded data.
+Certificates with large RSA keys, many Subject Alternative Names, or large
+custom extensions can exceed this. Check the DER size of the leaf certificate:
+
+```bash
+openssl x509 -in client.pem -outform der | wc -c
+```
+
+If the result is near or above ~10,000 bytes, reissue a smaller leaf
+certificate. Trim unnecessary extensions and SANs, or switch to ECDSA keys
+instead of large (4096-bit) RSA keys. This limit applies to the **leaf**
+certificate the edge forwards, not the full chain.
+
 ### `request.user.data.mtlsAuth` is missing
 
 - The policy only attaches metadata when a parseable client certificate is
   present on the request. Confirm the client is sending one.
 - Verify the route includes the `mtls-auth-inbound` policy.
+- If the certificate verifies but metadata is still missing, check the leaf
+  certificate size (see
+  [`client certificate metadata not provided`](#client-certificate-metadata-not-provided)).
 
 ### Custom domains
 
@@ -331,6 +407,27 @@ that custom domain.
 If you add a custom domain later and your clients aren't being verified against
 it, contact [support@zuplo.com](mailto:support@zuplo.com).
 
+### Custom domains behind your own CDN
+
+Inbound mTLS requires the TLS handshake to terminate at Zuplo's edge, because
+that's where the client certificate is verified and parsed. If you front your
+Zuplo gateway with **your own CDN** (for example, your own Cloudflare zone) that
+terminates TLS before traffic reaches Zuplo, the handshake — and the client
+certificate — ends at your CDN. Zuplo never sees the certificate, so the
+`mtls-auth-inbound` policy has nothing to verify.
+
+You have two supported options:
+
+- **Let Zuplo terminate TLS.** Point clients at a Zuplo-managed gateway domain,
+  or configure your custom domain directly on Zuplo so Zuplo terminates TLS. The
+  client certificate then reaches Zuplo's edge and inbound mTLS works as
+  documented above.
+- **Verify mTLS at your CDN.** If you must keep your own CDN in front, terminate
+  and verify the client certificate at the CDN, then forward the verified
+  identity to Zuplo in a request header. Validate that header in a Zuplo policy
+  instead of relying on `mtls-auth-inbound`. Make sure the header can't be
+  spoofed by clients that bypass your CDN.
+
 ## Additional resources
 
 - [`mtls-auth-inbound` policy reference](../policies/mtls-auth-inbound.mdx)

package/docs/guides/proxying-between-zuplo-gateways.mdx

@@ -0,0 +1,409 @@
+---
+title: Proxying Between Zuplo Gateways
+sidebar_label: Proxying Between Gateways
+description:
+  Learn how to proxy requests from one Zuplo project to another using the URL
+  Forward Handler or a custom fetch handler, propagate authentication, surface
+  upstream errors, and troubleshoot 522 timeouts.
+tags:
+  - backends
+  - deployment
+  - custom-code
+  - authentication
+---
+
+Some architectures call for one Zuplo gateway to sit in front of one or more
+other Zuplo gateways. A "product" gateway might aggregate several team-owned
+"member" gateways, a BFF might fan out to multiple internal APIs, or a migration
+might route a subset of traffic through a new project while the old one still
+serves the rest.
+
+This guide covers the patterns, auth propagation strategies, error-handling
+pitfalls, and troubleshooting steps you need when the upstream is another Zuplo
+project.
+
+## When this pattern makes sense
+
+- **Product-of-products** — A single public API endpoint forwards different path
+  prefixes to separate Zuplo projects, each owned by a different team.
+- **Backend for frontend (BFF)** — A gateway aggregates data from multiple
+  downstream Zuplo-managed APIs into a single response.
+- **Tenant routing** — Requests are routed to different Zuplo projects based on
+  tenant identity or API key metadata. See
+  [User-Based Backend Routing](./user-based-backend-routing.mdx) for a detailed
+  walkthrough of this approach.
+- **Gradual migration** — During a migration, a new gateway forwards unhandled
+  routes to the old gateway.
+
+If you use a Managed Dedicated deployment with an enterprise plan, consider
+[Federated Gateways](../dedicated/federated-gateways.mdx) instead. Federated
+Gateways is an enterprise add-on that uses the `local://` protocol for
+inter-environment communication within the same dedicated instance, avoiding the
+public internet and providing lower latency.
+
+## Choosing an approach
+
+### Pattern A: URL Forward Handler
+
+The [URL Forward Handler](../handlers/url-forward.mdx) is the simplest option.
+It proxies the request — method, headers, and body — to the downstream Zuplo
+project without writing any code.
+
+```json
+{
+  "handler": {
+    "export": "urlForwardHandler",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "baseUrl": "${env.DOWNSTREAM_GATEWAY_URL}"
+    }
+  }
+}
+```
+
+Store the downstream URL (for example
+`https://member-api-main-abc123.zuplo.app`) in an
+[environment variable](../articles/environment-variables.mdx) so you can change
+it per environment without modifying route configuration.
+
+The URL Forward Handler appends the incoming path to the `baseUrl`. If the outer
+gateway receives `GET /orders/123` and the `baseUrl` is
+`https://member-api-main-abc123.zuplo.app`, the forwarded request goes to
+`https://member-api-main-abc123.zuplo.app/orders/123`.
+
+**When to use this pattern:**
+
+- You want zero-code proxying and are happy forwarding the request as-is.
+- You do not need to inspect or transform the upstream response before returning
+  it to the caller.
+
+### Pattern B: Custom fetch handler
+
+A [Function Handler](../handlers/custom-handler.mdx) gives you full control over
+the outbound request and lets you inspect the upstream response before returning
+it to the caller. This is the recommended pattern when you need to propagate
+authentication credentials, transform the response, or surface upstream error
+details.
+
+```typescript
+import { ZuploContext, ZuploRequest, environment } from "@zuplo/runtime";
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+): Promise<Response> {
+  const url = new URL(request.url);
+  const upstreamUrl = `${environment.DOWNSTREAM_GATEWAY_URL}${url.pathname}${url.search}`;
+
+  const upstreamResponse = await fetch(upstreamUrl, {
+    method: request.method,
+    headers: request.headers,
+    body: request.body,
+  });
+
+  // Return the upstream response directly, preserving status and headers
+  return new Response(upstreamResponse.body, {
+    status: upstreamResponse.status,
+    headers: upstreamResponse.headers,
+  });
+}
+```
+
+**When to use this pattern:**
+
+- You need to add, remove, or transform headers before forwarding.
+- You need to read the upstream response body (for example, to merge responses
+  from multiple downstreams).
+- You want to return the exact upstream status code and body to the caller
+  instead of receiving an opaque 522. See
+  [Surfacing upstream errors](#surfacing-upstream-errors-instead-of-522) below.
+
+### Pattern C: Federated Gateways (Managed Dedicated)
+
+On a [Managed Dedicated](../dedicated/federated-gateways.mdx) plan, use the
+`local://` protocol to call other environments in the same instance:
+
+```json
+{
+  "handler": {
+    "export": "urlForwardHandler",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "baseUrl": "local://member-api-main-abc123"
+    }
+  }
+}
+```
+
+This avoids the public internet entirely. The Lambda handler is not supported
+for federated calls — use URL Forward, URL Rewrite, or a Function Handler
+instead.
+
+## Propagating authentication
+
+When the outer gateway authenticates a request (using
+[API Key Authentication](../concepts/api-keys.md),
+[JWT authentication](../concepts/authentication.mdx), or another method), the
+inner gateway still needs to trust that request. There are several patterns for
+propagating identity between gateways.
+
+### Forward the original credential
+
+The simplest approach is to forward the caller's original `Authorization` header
+(or API key header) to the downstream gateway. Both the URL Forward Handler and
+the custom fetch handler forward request headers by default, so if the
+downstream gateway accepts the same credentials, this works without extra
+configuration.
+
+:::caution
+
+If the outer and inner gateways use different API key buckets or different JWT
+issuers, forwarding the original credential does not work. Use one of the
+patterns below instead.
+
+:::
+
+### Shared secret header
+
+Store a shared secret in an
+[environment variable](../articles/environment-variables.mdx) on both projects.
+On the outer gateway, use a
+[Set Headers policy](../policies/set-headers-inbound.mdx) to add the secret as a
+custom header. On the inner gateway, validate the header in an inbound policy or
+use the same Set Headers policy to check the value.
+
+```json
+{
+  "name": "set-backend-secret",
+  "policyType": "set-headers-inbound",
+  "handler": {
+    "export": "SetHeadersInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "headers": [
+        {
+          "name": "x-gateway-secret",
+          "value": "$env(DOWNSTREAM_SECRET)"
+        }
+      ]
+    }
+  }
+}
+```
+
+See [Securing your backend](../articles/securing-your-backend.mdx) for a
+complete walkthrough of this approach.
+
+### Upstream Zuplo JWT
+
+The [Upstream Zuplo JWT policy](../policies/upstream-zuplo-jwt-auth-inbound.mdx)
+generates a short-lived, self-signed JWT and attaches it to the outbound
+request. Configure the inner gateway to validate this JWT using the
+[OpenID JWT Authentication policy](../policies/open-id-jwt-auth-inbound.mdx)
+with Zuplo's JWKS endpoint.
+
+This is the most robust option for service-to-service authentication between
+Zuplo projects because it does not require sharing static secrets and the token
+includes claims you can use for authorization on the downstream side.
+
+## Surfacing upstream errors instead of 522
+
+A common problem when proxying between Zuplo gateways: the downstream gateway
+returns a `401 Unauthorized` (or another error), but the caller sees a `522`
+instead.
+
+### Why this happens
+
+Zuplo's managed edge environment uses connection-level timeouts between the
+gateway and the origin server. A `522` status code means a connection-level
+failure occurred between the gateway and the upstream. The
+[Platform Limits](../articles/limits.mdx) documentation lists two scenarios that
+produce a 522: a Complete TCP Connection timeout at 19 seconds and a TCP ACK
+Timeout at 90 seconds.
+
+A `522` can also appear when the upstream closes the connection unexpectedly —
+for example, if the downstream gateway rejects the TLS handshake, returns a
+connection reset, or takes too long to send the response headers.
+
+When the downstream Zuplo project returns an HTTP error like `401` or `500`,
+that is **not** a 522. The 522 means the connection itself failed before an HTTP
+response was received. If you are seeing 522 instead of the expected upstream
+error, the issue is at the network or TLS layer, not the HTTP layer.
+
+### Common causes of 522 between Zuplo projects
+
+- **DNS resolution failure** — The downstream URL is incorrect or the
+  environment no longer exists.
+- **TLS handshake failure** — Misconfigured custom domain or certificate issue
+  on the downstream project.
+- **Connection timeout** — The downstream project takes longer than 19 seconds
+  to accept the TCP connection, usually because it is overloaded or
+  misconfigured.
+- **Egress restrictions** — In some network configurations, outbound connections
+  from one Zuplo project to another may be restricted.
+
+### Returning the actual upstream error
+
+If the TCP connection succeeds but the upstream returns an HTTP error (like 401
+or 500), the URL Forward Handler already returns that status code to the caller.
+You do not need to do anything extra — the upstream's status and body flow
+through.
+
+If you need more control (for example, to log the upstream error or transform it
+before returning), use a custom fetch handler:
+
+```typescript
+import { ZuploContext, ZuploRequest, environment } from "@zuplo/runtime";
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+): Promise<Response> {
+  const url = new URL(request.url);
+  const upstreamUrl = `${environment.DOWNSTREAM_GATEWAY_URL}${url.pathname}${url.search}`;
+
+  try {
+    const upstreamResponse = await fetch(upstreamUrl, {
+      method: request.method,
+      headers: request.headers,
+      body: request.body,
+    });
+
+    if (!upstreamResponse.ok) {
+      context.log.warn(
+        `Upstream returned ${upstreamResponse.status} for ${url.pathname}`,
+      );
+    }
+
+    return new Response(upstreamResponse.body, {
+      status: upstreamResponse.status,
+      headers: upstreamResponse.headers,
+    });
+  } catch (error) {
+    context.log.error(`Failed to reach upstream: ${error}`);
+    return new Response(
+      JSON.stringify({
+        type: "https://httpproblems.com/http-status/502",
+        title: "Bad Gateway",
+        status: 502,
+        detail: "The upstream service is unreachable.",
+      }),
+      {
+        status: 502,
+        headers: { "content-type": "application/problem+json" },
+      },
+    );
+  }
+}
+```
+
+This handler catches connection-level errors (which would otherwise surface as
+a 522) and returns a structured `502 Bad Gateway` response. When the upstream
+does return an HTTP response, the status and body pass through unchanged.
+
+## Custom domains across the fleet
+
+When multiple Zuplo projects form a gateway chain, decide where to attach your
+[custom domain](../articles/custom-domains.mdx):
+
+- **Outer gateway only** — The most common setup. Attach your custom domain (for
+  example, `api.example.com`) to the outer gateway project and let the inner
+  gateways use their default `*.zuplo.app` URLs. Callers only see your custom
+  domain.
+- **Every gateway** — Useful when internal teams also call the inner gateways
+  directly for testing or monitoring. Each project gets its own custom domain.
+
+:::tip
+
+Putting the custom domain only on the outer gateway simplifies DNS management
+and certificate renewal. The inner gateways are implementation details that
+callers do not need to know about.
+
+:::
+
+## Cost considerations
+
+Request traffic is metered at the account level, and every project in the chain
+counts against the same shared allowance. A single client request that fans out
+to three downstream Zuplo projects results in four billed requests: one on the
+outer gateway and one on each downstream project.
+
+Review [Platform Limits](../articles/limits.mdx) and your plan's monthly request
+allowance before designing a fan-out architecture. If the request volume is
+high, consider whether a single Zuplo project with path-based routing can
+replace the multi-project topology.
+
+## Troubleshooting
+
+### 522 with no logs on the downstream project
+
+The outer gateway's runtime could not establish a TCP connection to the
+downstream project. The request never reached the inner gateway, so there are no
+logs there.
+
+**Checklist:**
+
+1. Verify the downstream URL is correct. Check the environment variable value in
+   the outer gateway project. A typo in the environment name (for example,
+   `main` instead of `main-abc123`) produces a DNS failure.
+2. Confirm the downstream project is deployed and its environment is active.
+   Open the downstream project in the [Zuplo Portal](https://portal.zuplo.com)
+   and check the environment status.
+3. If using a custom domain on the downstream project, verify the DNS CNAME
+   record points to `cname.zuplo.app` and the certificate is valid.
+
+### 522 only when forwarding to another Zuplo project
+
+Requests to `httpbin.org` or other external services work fine, but requests to
+`*.zuplo.app` return 522.
+
+**Checklist:**
+
+1. Check that the downstream Zuplo project's environment is not a development
+   environment (ending in `.zuplo.dev`). Development environments have stricter
+   rate limits (1,000 requests per minute) and may reject connections under
+   load.
+2. Verify TLS is working — the outer gateway connects to the downstream over
+   HTTPS. If the downstream has a custom domain with certificate issues, the TLS
+   handshake fails and produces a 522.
+3. Look at the outer gateway's logs for connection error details. The Zuplo
+   runtime logs include the error message when an outbound `fetch` fails.
+
+### Caller receives the upstream 401 directly
+
+This is the expected behavior. The URL Forward Handler and custom fetch handlers
+both return the upstream's HTTP status and body as-is. If the caller sees `401`,
+the downstream project rejected the request at the HTTP level (not a connection
+failure).
+
+If the downstream uses API key authentication and the caller's key is not valid
+on the downstream project, the downstream returns `401`. Review the
+[Propagating authentication](#propagating-authentication) section to choose the
+right credential strategy.
+
+### Mismatched response content types
+
+The downstream project returns JSON but the caller receives an unexpected
+content type or an empty body.
+
+**Checklist:**
+
+1. Verify the downstream route is configured to return the expected content
+   type. Check the handler and outbound policies on the downstream project.
+2. If using a custom fetch handler on the outer gateway, make sure you are
+   forwarding the upstream's `content-type` header. The example handler in
+   [Pattern B](#pattern-b-custom-fetch-handler) preserves all upstream headers.
+3. Check whether an outbound policy on the outer gateway transforms or strips
+   the response body.
+
+## Related resources
+
+- [URL Forward Handler](../handlers/url-forward.mdx)
+- [Function Handler](../handlers/custom-handler.mdx)
+- [Federated Gateways (Managed Dedicated)](../dedicated/federated-gateways.mdx)
+- [Securing your backend](../articles/securing-your-backend.mdx)
+- [Platform Limits](../articles/limits.mdx)
+- [Gateway Timeout error](../errors/gateway-timeout.mdx)
+- [Request Lifecycle](../concepts/request-lifecycle.mdx)
+- [Custom Domains](../articles/custom-domains.mdx)
+- [Environment Variables](../articles/environment-variables.mdx)

package/docs/guides/transform-route-params-url-rewrite.mdx

@@ -0,0 +1,307 @@
+---
+title: Transform Route Parameters for URL Rewrite
+sidebar_label: Transform Route Parameters
+description:
+  Learn how to use an inbound policy to transform route parameter values before
+  the URL Rewrite handler forwards the request to your backend.
+tags:
+  - custom-code
+  - backends
+---
+
+This guide explains how to transform incoming route parameter values in an
+inbound policy before the [URL Rewrite handler](../handlers/url-rewrite.mdx)
+uses them to build the upstream URL. This pattern is useful when your public API
+paths use different naming conventions than your internal backend.
+
+## Overview
+
+When you use the URL Rewrite handler, it builds the upstream URL by
+interpolating values like `${params.resourceType}` directly from the incoming
+route parameters. Sometimes, however, you need to **change** those values before
+the rewrite happens. Common scenarios include:
+
+- **Value mapping** — translating a public-facing parameter like `order` to an
+  internal value like `customerorder`
+- **Case normalization** — converting `Products` to `products` before forwarding
+- **Path translation** — mapping user-friendly slugs to internal identifiers
+
+The recommended approach is to read the route parameters in an inbound policy,
+transform them, store the results on
+[`context.custom`](../programmable-api/zuplo-context.mdx), and reference the
+transformed values in the URL Rewrite pattern.
+
+## Step-by-Step Example
+
+The solution has three parts: an **inbound policy** that reads `request.params`
+and stores transformed values on `context.custom`, a **URL Rewrite handler**
+that references those values using `${context.custom.*}` in the
+`rewritePattern`, and **route configuration** that wires the two together.
+
+Imagine your public API exposes a route like `/api/:resourceType/:resourceId`,
+but your backend expects the resource type to be prefixed with `customer`. A
+request to `/api/order/123` should be forwarded to
+`https://backend.example.com/api/customerorder/123`.
+
+### 1. Write the Inbound Policy
+
+Create a custom inbound policy that reads the route parameters, transforms the
+values, and stores them on `context.custom`:
+
+```ts title="modules/transform-params.ts"
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: any,
+  policyName: string,
+): Promise<ZuploRequest | Response> {
+  // Read the original route parameter
+  const resourceType = request.params.resourceType;
+
+  // Transform the value — prefix with "customer"
+  const transformedResourceType = `customer${resourceType}`;
+
+  // Store the transformed value on context.custom
+  context.custom.transformedResourceType = transformedResourceType;
+
+  context.log.info({
+    message: "Transformed route parameter",
+    original: resourceType,
+    transformed: transformedResourceType,
+  });
+
+  return request;
+}
+```
+
+### 2. Register the Policy
+
+Add the policy to `config/policies.json`:
+
+```json title="config/policies.json"
+{
+  "policies": [
+    {
+      "name": "transform-params",
+      "policyType": "custom-code-inbound",
+      "handler": {
+        "export": "default",
+        "module": "$import(./modules/transform-params)"
+      }
+    }
+  ]
+}
+```
+
+### 3. Configure the Route
+
+Define the route in `config/routes.oas.json` with the inbound policy and a URL
+Rewrite handler that references `context.custom`:
+
+```json title="config/routes.oas.json"
+{
+  "paths": {
+    "/api/{resourceType}/{resourceId}": {
+      "x-zuplo-path": {
+        "pathMode": "open-api"
+      },
+      "get": {
+        "summary": "Get resource by type and ID",
+        "x-zuplo-route": {
+          "corsPolicy": "none",
+          "handler": {
+            "export": "urlRewriteHandler",
+            "module": "$import(@zuplo/runtime)",
+            "options": {
+              "rewritePattern": "https://backend.example.com/api/${context.custom.transformedResourceType}/${params.resourceId}"
+            }
+          },
+          "policies": {
+            "inbound": ["transform-params"]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+With this configuration, a request to `/api/order/123` flows through the
+pipeline as follows:
+
+1. The route matches with `params.resourceType = "order"` and
+   `params.resourceId = "123"`
+2. The `transform-params` inbound policy runs and sets
+   `context.custom.transformedResourceType = "customerorder"`
+3. The URL Rewrite handler builds the upstream URL:
+   `https://backend.example.com/api/customerorder/123`
+
+## Common Pitfall: Modifying `request.params` Directly
+
+:::caution
+
+Do not try to transform route parameters by constructing a new `ZuploRequest`
+with modified `params` and expecting the URL Rewrite handler to pick them up.
+
+:::
+
+A common first attempt is to create a new
+[`ZuploRequest`](../programmable-api/zuplo-request.mdx) with different `params`:
+
+```ts
+// ⚠️ This approach does NOT work as expected with URL Rewrite
+const newRequest = new ZuploRequest(request, {
+  params: {
+    ...request.params,
+    resourceType: "customerorder",
+  },
+});
+return newRequest;
+```
+
+In practice, the URL Rewrite handler evaluates `${params.*}` against the
+route-level parameters rather than the request object returned by a policy. This
+means the rewritten URL may contain `undefined` segments instead of your
+transformed values. Use `context.custom` for reliable interpolation of
+transformed values — the URL Rewrite handler's `rewritePattern` fully supports
+`${context.custom.*}`, and values set in an inbound policy are available when
+the handler runs.
+
+## Variations
+
+### Using a Lookup Map
+
+For more complex mappings where the transformation is not a simple string
+operation, use a lookup object:
+
+```ts title="modules/transform-params-map.ts"
+import { ZuploContext, ZuploRequest, HttpProblems } from "@zuplo/runtime";
+
+// Map public resource types to internal names
+const RESOURCE_TYPE_MAP: Record<string, string> = {
+  order: "customerorder",
+  invoice: "billing-invoice",
+  profile: "user-profile",
+  subscription: "recurring-plan",
+};
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: any,
+  policyName: string,
+): Promise<ZuploRequest | Response> {
+  const resourceType = request.params.resourceType;
+  const mappedType = RESOURCE_TYPE_MAP[resourceType];
+
+  if (!mappedType) {
+    return HttpProblems.notFound(request, context, {
+      detail: `Unknown resource type: ${resourceType}`,
+    });
+  }
+
+  context.custom.transformedResourceType = mappedType;
+
+  return request;
+}
+```
+
+### Transforming Multiple Parameters
+
+You can transform any number of route parameters and store each on
+`context.custom`. Reference them individually in the rewrite pattern:
+
+```ts title="modules/transform-multiple-params.ts"
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: any,
+  policyName: string,
+): Promise<ZuploRequest | Response> {
+  // Normalize casing
+  context.custom.version = request.params.version?.toLowerCase();
+
+  // Map resource type
+  context.custom.resource =
+    request.params.resource === "users" ? "customers" : request.params.resource;
+
+  return request;
+}
+```
+
+Then use both values in the rewrite pattern:
+
+```json
+{
+  "rewritePattern": "https://backend.example.com/${context.custom.version}/${context.custom.resource}/${params.id}"
+}
+```
+
+### Combining with Body Transformation
+
+If your API also needs to transform values in the request body alongside route
+parameters, you can handle both in the same inbound policy. Create a new
+`ZuploRequest` with a modified body while storing the route parameter
+transformations on `context.custom`:
+
+```ts title="modules/transform-params-and-body.ts"
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: any,
+  policyName: string,
+): Promise<ZuploRequest | Response> {
+  // Transform route parameter
+  context.custom.transformedResourceType = `customer${request.params.resourceType}`;
+
+  // Transform the request body if present
+  if (request.headers.get("content-type")?.includes("application/json")) {
+    const body = await request.json();
+
+    // Map fields in the body to match the backend schema
+    const transformedBody = {
+      ...body,
+      type: context.custom.transformedResourceType,
+    };
+
+    // Return a new request with the modified body
+    return new ZuploRequest(request, {
+      body: JSON.stringify(transformedBody),
+    });
+  }
+
+  return request;
+}
+```
+
+## Best Practices
+
+- **Use descriptive keys on `context.custom`** — names like
+  `context.custom.transformedResourceType` are easier to debug than generic keys
+  like `context.custom.value`
+- **Log transformations** — use `context.log` to record original and transformed
+  values so you can trace issues in production
+- **Validate before transforming** — return an appropriate error response (using
+  [`HttpProblems`](../programmable-api/http-problems.mdx)) if a parameter value
+  is unexpected, rather than forwarding bad data to your backend
+- **Keep the policy focused** — if your transformation logic is complex,
+  consider splitting it into a separate utility module imported by the policy
+
+## Next Steps
+
+- [URL Rewrite Handler](../handlers/url-rewrite.mdx) — full reference for
+  rewrite patterns and available interpolation variables
+- [Custom Code Patterns](../articles/custom-code-patterns.md) — common patterns
+  for writing inbound policies, outbound policies, and handlers
+- [ZuploContext](../programmable-api/zuplo-context.mdx) — reference for
+  `context.custom` and other context properties
+- [ZuploRequest](../programmable-api/zuplo-request.mdx) — reference for
+  `request.params` and constructing new requests
+- [User-Based Backend Routing](./user-based-backend-routing.mdx) — a related
+  pattern using `context.custom` with URL Rewrite for routing by user identity

package/docs/handlers/mcp-server.mdx

@@ -121,6 +121,17 @@ client, ensure your `outputSchema` is a valid `type: object` JSON Schema and
   included as `structuredContent`. When `false`, only `text` content will be
   returned.
 
+:::caution
+
+Enable `includeOutputSchema` and `includeStructuredContent` together. Turning on
+`includeOutputSchema` alone makes the server advertise an output schema while
+returning only `text` content, which causes MCP clients to fail tool calls with
+`Tool call failed: 500`. See
+[Troubleshooting the MCP Server Handler](../mcp-server/troubleshooting.mdx) for
+how to diagnose and fix this.
+
+:::
+
 ### Operations
 
 Configure MCP tools, prompts, and resources using the `operations`

package/docs/mcp-server/troubleshooting.mdx

@@ -0,0 +1,195 @@
+---
+title: "Troubleshooting the MCP Server Handler"
+sidebar_label: "Troubleshooting"
+description:
+  Diagnose MCP Server handler tool calls that fail in an AI client even though
+  the gateway route returns 200, using debug logging and the structured-content
+  configuration.
+---
+
+When an AI client calls a tool exposed by the
+[MCP Server handler](../handlers/mcp-server.mdx), a failure often surfaces as
+nothing more than `Tool call failed: 500`, with no indication of _why_. The
+underlying gateway route can return `200` while the MCP client still rejects the
+response, which makes these failures hard to diagnose from the client alone.
+
+This page shows how to turn on the handler's debug logging, read the log lines
+that reveal a misconfiguration, and fix the most common cause: a tool that
+advertises an output schema but returns no structured content.
+
+:::tip
+
+Most "200 on the gateway, error in the client" failures come from the
+[`includeOutputSchema` and `includeStructuredContent` options](../handlers/mcp-server.mdx#mcp-2025-06-18-global-options).
+If you enabled one without the other, jump straight to
+[Tool call failed: 500](#tool-call-failed-500--has-an-output-schema-but-did-not-return-structured-content).
+
+:::
+
+## Enable debug logging
+
+The MCP Server handler can emit verbose logs covering server startup, tool
+registration, and each tool call. These logs are the fastest way to confirm what
+the server actually advertised to the client.
+
+<Stepper>
+
+1. **Turn on `debugMode`.** Set `debugMode: true` in the handler options for
+   your MCP route in `routes.oas.json`:
+
+   ```json
+   "post": {
+     "x-zuplo-route": {
+       "handler": {
+         "export": "mcpServerHandler",
+         "module": "$import(@zuplo/runtime)",
+         "options": {
+           "name": "example-mcp-server",
+           "version": "1.0.0",
+           "debugMode": true
+         }
+       }
+     }
+   }
+   ```
+
+2. **Redeploy so the server cold-starts.** Some of the most useful log lines —
+   server startup and tool registration — are written only when the MCP server
+   initializes (a cold start). An already-running worker won't re-emit them.
+   Deploy the working copy or environment again so a fresh worker boots with
+   `debugMode` enabled.
+
+3. **View the logs.** Open your project in the Portal and go to **Observability
+   → Logs**. Trigger a tool call from your MCP client, then read the entries for
+   the MCP route. Filter on the request's `zuplo-request-id` to isolate a single
+   call.
+
+</Stepper>
+
+:::caution
+
+Leave `debugMode` off in production. It logs verbose per-call detail that adds
+noise and overhead. Turn it on to diagnose an issue, then turn it back off and
+redeploy.
+
+:::
+
+### Key log lines to read
+
+With `debugMode: true`, the handler writes lines at each stage of its lifecycle.
+The exact format may change between runtime versions, but the fields below are
+what you're looking for:
+
+| Log line                       | When it's written       | What to check                                                          |
+| ------------------------------ | ----------------------- | ---------------------------------------------------------------------- |
+| `MCP Server cold start`        | A fresh worker boots    | Confirms `debugMode` is active and a new worker started                |
+| `MCP tool registered`          | Each tool is registered | The `includeStructuredContent` and `hasOutputSchema` fields for a tool |
+| `MCP Server response complete` | A tool call finishes    | The response was produced and sent back to the client                  |
+
+The `MCP tool registered` line is the important one. For a tool whose calls fail
+in the client, you'll typically see a line resembling:
+
+```
+MCP tool registered { name: "get_current_weather", hasOutputSchema: true, includeStructuredContent: false }
+```
+
+`hasOutputSchema: true` with `includeStructuredContent: false` is the exact
+misconfiguration described in the next section.
+
+## Tool call failed: 500 / "has an output schema but did not return structured content"
+
+**Symptom.** An AI client (such as Claude) reports `Tool call failed: 500` when
+it invokes a tool. With more verbose client logging, the underlying error reads:
+
+```
+Tool <tool_name> has an output schema but did not return structured content
+```
+
+Meanwhile, the gateway's own logs show the route that backs the tool returned
+`200`.
+
+**Likely cause.** The handler is configured with `includeOutputSchema: true` but
+not `includeStructuredContent: true`. Under the
+[MCP `2025-06-18`](https://modelcontextprotocol.io/specification/2025-06-18)
+structured-content behavior, when a tool advertises an `outputSchema`, the
+client expects every successful result to include a matching `structuredContent`
+object. With `includeOutputSchema` on and `includeStructuredContent` off, the
+server advertises the schema but returns only `text` content, so a
+spec-compliant client rejects an otherwise-successful `200` response.
+
+The `MCP tool registered` debug line confirms it:
+`hasOutputSchema: true, includeStructuredContent: false`.
+
+**Fix.** Enable both options together on the MCP Server handler:
+
+```json
+"options": {
+  "name": "example-mcp-server",
+  "version": "1.0.0",
+  "includeOutputSchema": true,
+  "includeStructuredContent": true
+}
+```
+
+Then redeploy. The next `MCP tool registered` line should read
+`hasOutputSchema: true, includeStructuredContent: true`, and the tool call
+succeeds.
+
+:::note
+
+If you don't need output schemas at all, the alternative fix is to turn both off
+(the defaults). The two options are designed to move together: enable
+`includeOutputSchema` _only_ alongside `includeStructuredContent`.
+
+:::
+
+For the full definitions of both options, see the
+[MCP `2025-06-18` Global Options](../handlers/mcp-server.mdx#mcp-2025-06-18-global-options)
+in the handler reference.
+
+## Client-side debugging tools
+
+When the gateway looks healthy, reproduce the failure against the client to see
+the protocol-level error the AI client hides:
+
+- **MCP Inspector** — the
+  [official inspector](https://github.com/modelcontextprotocol/inspector)
+  (`npx @modelcontextprotocol/inspector`) connects to your remote server, lists
+  tools, and calls them while showing the raw JSON-RPC messages. See
+  [Testing](./testing.mdx) for connection steps.
+- **mcpjam** — the [mcpjam inspector](https://github.com/mcpjam/inspector) is an
+  open-source MCP testing client that's useful for exercising tool calls and
+  inspecting responses outside of an AI client.
+- **Claude Code** — run with the `--debug` flag (for example, `claude --debug`)
+  to print MCP protocol traffic, including the full tool-call error that the
+  chat UI summarizes as `Tool call failed: 500`.
+
+## Checklist: the gateway returns 200 but the client errors
+
+When a tool call fails in the client but the gateway reports success, verify
+each of these in order:
+
+1. **`debugMode` is on and a fresh worker booted.** Confirm a
+   `MCP Server cold start` line appears after your latest deploy. Without a cold
+   start, you're reading stale logs.
+2. **Schema and structured content move together.** In the `MCP tool registered`
+   line, `hasOutputSchema` and `includeStructuredContent` should either both be
+   `true` or both be `false` — never `hasOutputSchema: true` with
+   `includeStructuredContent: false`.
+3. **The output schema is a valid `type: object` JSON Schema.** Some clients
+   reject schemas that aren't `type: object`. The same applies to the
+   `structuredContent` the server returns. See the
+   [compatibility caveat](../handlers/mcp-server.mdx#mcp-2025-06-18-global-options).
+4. **The route really returns JSON.** `includeStructuredContent` parses the
+   response body as JSON to build `structuredContent`. A non-JSON `200` body
+   can't be parsed into the advertised schema.
+5. **Reproduce in a raw client.** Call the tool through the
+   [MCP Inspector](./testing.mdx) or `curl` to read the JSON-RPC error directly,
+   rather than the client's summarized `500`.
+
+## Next steps
+
+- [MCP Server handler reference](../handlers/mcp-server.mdx) — every handler
+  configuration option.
+- [Testing your MCP server](./testing.mdx) — MCP Inspector and `curl` recipes.
+- [MCP Server tools](./tools.mdx) — editing tool definitions and `outputSchema`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "6.71.9",
+  "version": "6.71.11",
   "type": "module",
   "description": "The programmable API Gateway",
   "author": "Zuplo, Inc.",
@@ -19,9 +19,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "6.71.9",
-    "@zuplo/core": "6.71.9",
-    "@zuplo/runtime": "6.71.9",
+    "@zuplo/cli": "6.71.11",
+    "@zuplo/core": "6.71.11",
+    "@zuplo/runtime": "6.71.11",
     "@zuplo/test": "1.4.0"
   }
 }