zuplo 6.69.9 → 6.69.11

package/docs/articles/monetization/stripe-integration.md

@@ -42,7 +42,9 @@ in Stripe at the moment a charge is needed (as invoice line items).
 
 ### Via the Zuplo Portal
 
-1. Navigate to **Services → Monetization Service → Payment Provider**
+1. Open your project's
+   [**Services**](https://portal.zuplo.com/+/account/project/services) page,
+   select the Monetization Service, then go to **Payment Provider**
 2. Click **Configure** on the Stripe card
 3. Enter a **Name** and paste your **Stripe API Key**
 4. Click **Save**
@@ -111,8 +113,10 @@ Intents, Refunds, or Stripe Billing Meters — leave all of those at **None**.
    or `Zuplo Monetization (production)`.
 3. For each of the eight permissions above, set the level shown in the table.
 4. Click **Create key**, copy the value (`rk_test_...` or `rk_live_...`), and
-   paste it into **Services → Monetization Service → Payment Provider** in your
-   Zuplo project.
+   paste it into the Monetization Service's **Payment Provider** screen (open
+   your project's
+   [**Services**](https://portal.zuplo.com/+/account/project/services) page,
+   then the Monetization Service) in your Zuplo project.
 
 :::caution
 
@@ -208,22 +212,22 @@ When a customer cancels through the Developer Portal, the timing of the
 cancellation depends on whether the current phase has billable items:
 
 - **Paid phases** — the portal sends `timing: "next_billing_cycle"`. The
-  subscription is scheduled to cancel at the end of the current billing
-  period, the customer retains access until then, and the API key stops
-  working at period end.
+  subscription is scheduled to cancel at the end of the current billing period,
+  the customer retains access until then, and the API key stops working at
+  period end.
 - **Free phases** — the portal sends `timing: "immediate"`. With nothing to
   invoice at period end, there's no billing period to wait out, so the
   subscription cancels and access is revoked right away. Two situations fall
   into this branch:
-  - The customer is on a **free trial phase** (the first phase of a plan
-    with a later paid phase) and cancels before the trial converts.
-  - The customer is on a **free plan** — a plan whose only phase has no
-    billable rate cards (every rate card's `price` is `null`).
+  - The customer is on a **free trial phase** (the first phase of a plan with a
+    later paid phase) and cancels before the trial converts.
+  - The customer is on a **free plan** — a plan whose only phase has no billable
+    rate cards (every rate card's `price` is `null`).
 
 For programmatic cancellation, see
 [Cancellation](./subscription-lifecycle.md#cancellation) in the Subscription
-Lifecycle guide — the API endpoint accepts a `timing` parameter to control
-this same behavior explicitly.
+Lifecycle guide — the API endpoint accepts a `timing` parameter to control this
+same behavior explicitly.
 
 ## Proration
 

package/docs/articles/monetization/subscription-lifecycle.md

@@ -104,9 +104,9 @@ API is needed.
       "rateCards": [
         {
           "type": "flat_fee",
-          "key": "api_calls",
+          "key": "api_requests",
           "name": "API Calls",
-          "featureKey": "api_calls",
+          "featureKey": "api_requests",
           "billingCadence": null,
           "price": null,
           "entitlementTemplate": {
@@ -124,9 +124,9 @@ API is needed.
       "rateCards": [
         {
           "type": "usage_based",
-          "key": "api_calls",
+          "key": "api_requests",
           "name": "API Calls",
-          "featureKey": "api_calls",
+          "featureKey": "api_requests",
           "billingCadence": "P1M",
           "price": {
             "type": "tiered",

package/docs/articles/monorepo-deployment.mdx

@@ -220,8 +220,7 @@ jobs:
 
 Store your Zuplo API key as a GitHub Actions secret:
 
-1. Go to [portal.zuplo.com](https://portal.zuplo.com) and navigate to your
-   account **Settings** > **API Keys**
+1. In the Zuplo Portal, navigate to your account **Settings** > **API Keys**
 2. Copy the API key
 3. In your GitHub repository, go to **Settings** > **Secrets and variables** >
    **Actions**
@@ -322,7 +321,7 @@ the deployed environment. Timeouts can indicate:
   `routes.oas.json` or `policies.json` exist in the `modules/` directory
 - **Missing environment variables** — If your policies or handlers reference
   environment variables with `$env(VAR_NAME)`, make sure those variables are
-  configured in the Zuplo portal under your project's
+  configured in the Zuplo Portal under your project's
   [environment variables](./environment-variables.mdx)
 
 ### Build succeeds but deploy fails

package/docs/articles/source-control-setup-github.mdx

@@ -18,10 +18,12 @@ new Zuplo project.
 
 1. Connect to GitHub
 
-   Go to your project in the Zuplo portal, click **Settings**, then select
-   **Source Control**. If your project isn't already connected to GitHub click
-   the **Connect to GitHub** button and follow the auth flow. You'll need to
-   grant permissions for any GitHub organizations you want to work with.
+   Open your
+   [project settings](https://portal.zuplo.com/+/account/project/settings/general)
+   in the Zuplo Portal, then select **Source Control**. If your project isn't
+   already connected to GitHub click the **Connect to GitHub** button and follow
+   the auth flow. You'll need to grant permissions for any GitHub organizations
+   you want to work with.
 
    ![Connect GitHub](../../public/media/step-4-deploying-to-the-edge/image-1.png)
 

package/docs/articles/step-1-setup-basic-gateway.mdx

@@ -18,9 +18,9 @@ Note - Zuplo also supports building and running your API locally. To learn more
 
 1. **Sign-in**
 
-   Sign in to [portal.zuplo.com](https://portal.zuplo.com) and create a free
-   account. Create a new **empty** project (don't import an existing project,
-   we'll set up git later). Then...
+   Sign in to the Zuplo Portal and create a free account. Then
+   [create a new empty project](https://portal.zuplo.com/+/account/projects/new)
+   (don't import an existing project, we'll set up git later). Then...
 
 1. Add your first **Route**
 

package/docs/articles/step-3-add-api-key-auth-local.mdx

@@ -102,9 +102,10 @@ Let's get started.
 
 1.  Set up an API Key
 
-    In order to call your API, you need to configure an API consumer. Go to the
-    [Zuplo Portal](https://portal.zuplo.com), then open the project you are
-    working on, **Services**, then click **Configure** on the "API Key Service".
+    In order to call your API, you need to configure an API consumer. In the
+    Zuplo Portal, open the
+    [**Services**](https://portal.zuplo.com/+/account/project/services) tab for
+    your project, then click **Configure** on the "API Key Service".
 
     :::warning
 

package/docs/articles/step-3-add-api-key-auth.mdx

@@ -69,8 +69,9 @@ Let's get started.
 
 2. Set up an API Key
 
-   In order to call your API, you need to configure an API consumer. Go to
-   **Services**, then click **Configure** on the "API Key Service".
+   In order to call your API, you need to configure an API consumer. Open the
+   [**Services**](https://portal.zuplo.com/+/account/project/services) tab in
+   your project, then click **Configure** on the "API Key Service".
 
    ![API Key Service](../../public/media/step-3-add-api-key-auth/image-2.png)
 

package/docs/articles/step-4-deploying-to-the-edge.mdx

@@ -30,10 +30,12 @@ Let's get started:
 
 1. Authorize to GitHub
 
-   Next, go to your project in the Zuplo portal, click **Settings**, then select
-   **Source Control**. If your project isn't already connected to GitHub click
-   the **Connect to GitHub** button and follow the auth flow. You'll need to
-   grant permissions for any GitHub organizations you want to work with.
+   Next, open your
+   [project settings](https://portal.zuplo.com/+/account/project/settings/general)
+   in the Zuplo Portal, then select **Source Control**. If your project isn't
+   already connected to GitHub click the **Connect to GitHub** button and follow
+   the auth flow. You'll need to grant permissions for any GitHub organizations
+   you want to work with.
 
    ![Connect GitHub](../../public/media/step-4-deploying-to-the-edge/image-1.png)
 

package/docs/articles/testing.mdx

@@ -78,9 +78,10 @@ The `.env.zuplo` file can contain sensitive information. Add it to your
 :::
 
 Once linked, services like the API Key Authentication policy work locally using
-the same API key bucket as the linked environment. You can create API key
-consumers in the [Zuplo Portal](https://portal.zuplo.com) under **Services > API
-Key Service**, then call your local gateway with the generated key:
+the same API key bucket as the linked environment. In the Zuplo Portal, open the
+[**Services**](https://portal.zuplo.com/+/account/project/services) tab in your
+project and select **API Key Service** to create API key consumers, then call
+your local gateway with the generated key:
 
 ```bash
 curl http://localhost:9000/your-route \

package/docs/articles/troubleshooting.md

@@ -79,7 +79,9 @@ arrays.
 The gateway returns this error when the project has a critical configuration
 issue that prevents it from starting.
 
-**Fix:** Check the deployment logs in the Zuplo Portal for the specific error
+**Fix:** Check the deployment logs in the Zuplo Portal — open the
+[**Environments**](https://portal.zuplo.com/+/account/project/environments) tab
+in your project and select the failing environment to see the specific error
 message. Common causes include invalid `zuplo.runtime.ts` configuration or
 broken runtime extensions.
 
@@ -174,9 +176,10 @@ const response = await fetch("https://api.example.com/data", {
 
 ### Portal live logs
 
-The Zuplo Portal provides real-time log viewing for deployed environments.
-Navigate to your project in the portal and open the logs tab to see live request
-logs and any messages logged with `context.log`.
+The Zuplo Portal provides real-time log viewing for deployed environments. Open
+the [**Environments**](https://portal.zuplo.com/+/account/project/environments)
+tab in your project, select the deployed environment, and open the logs tab to
+see live request logs and any messages logged with `context.log`.
 
 ### Using context.log
 

package/docs/cli/authentication.mdx

@@ -37,8 +37,10 @@ following these steps:
 
 1. Navigate to [portal.zuplo.com](https://portal.zuplo.com) and log in.
 2. Select the account that you want to work on.
-3. Click the **Settings** tab and navigate to the "API Keys" section. Select an
-   existing API Key or create a new one to use with the CLI.
+3. Navigate to
+   [**Settings → API Keys**](https://portal.zuplo.com/+/account/settings/api-keys)
+   in your account. Select an existing API Key or create a new one to use with
+   the CLI.
 
 Most commands take an `--api-key` argument. For example, to list your available
 Zuplo API Gateways, run:

package/docs/cli/bucket-list.mdx

@@ -0,0 +1,71 @@
+---
+title: "Zuplo CLI: Bucket List"
+sidebar_label: bucket list
+---
+
+<CliCommand
+  command="bucket list"
+  description="Lists the buckets in your account"
+  options={[
+  {
+    "name": "account",
+    "type": "string",
+    "description": "The account name",
+    "required": false,
+    "deprecated": false,
+    "hidden": false
+  },
+  {
+    "name": "project",
+    "type": "string",
+    "description": "Filter buckets by project name",
+    "required": false,
+    "deprecated": false,
+    "hidden": false
+  },
+  {
+    "name": "output",
+    "type": "string",
+    "description": "Output format",
+    "default": "default",
+    "required": false,
+    "deprecated": false,
+    "hidden": false,
+    "alias": [
+      "o"
+    ],
+    "choices": [
+      "default",
+      "json"
+    ]
+  }
+]}
+  examples={[
+  [
+    "$0 bucket list",
+    "List all buckets in your account"
+  ],
+  [
+    "$0 bucket list --output json",
+    "List all buckets as JSON"
+  ],
+  [
+    "$0 bucket list --account my-account",
+    "Explicitly specify the account"
+  ],
+  [
+    "$0 bucket list --project my-project",
+    "Filter buckets by project name"
+  ]
+]}
+  usage="$0 bucket list [options]"
+>
+
+</CliCommand>
+
+## Global options
+
+The following global options are available for all commands:
+
+- [`--help`](./global-options.mdx#help)
+- [`--api-key`](./global-options.mdx#api-key)

package/docs/cli/deploy.mdx

@@ -140,7 +140,8 @@ POLL_INTERVAL=5000 MAX_POLL_RETRIES=300 zuplo deploy
 ```
 
 Note, that even if the CLI times out, the deployment will continue. You can
-check the status of the deployment in the Zuplo portal.
+check the status of the deployment in your
+[project](https://portal.zuplo.com/+/account/project/) in the Zuplo Portal.
 
 </CliCommand>
 

package/docs/cli/deploy.partial.mdx

@@ -43,4 +43,5 @@ POLL_INTERVAL=5000 MAX_POLL_RETRIES=300 zuplo deploy
 ```
 
 Note, that even if the CLI times out, the deployment will continue. You can
-check the status of the deployment in the Zuplo portal.
+check the status of the deployment in your
+[project](https://portal.zuplo.com/+/account/project/) in the Zuplo Portal.

package/docs/cli/logout.mdx

@@ -0,0 +1,25 @@
+---
+title: "Zuplo CLI: Logout"
+sidebar_label: logout
+---
+
+<CliCommand
+  command="logout"
+  description="Logs the current user out if logged in"
+  examples={[
+  [
+    "$0 logout",
+    "Remove locally stored Zuplo credentials"
+  ]
+]}
+  usage="$0 logout"
+>
+
+</CliCommand>
+
+## Global options
+
+The following global options are available for all commands:
+
+- [`--help`](./global-options.mdx#help)
+- [`--api-key`](./global-options.mdx#api-key)

package/docs/concepts/api-keys.md

@@ -23,7 +23,8 @@ The API key system has three core objects:
 See [API Key Management](../articles/api-key-management.mdx) for a full
 overview, and
 [Manage Keys in the Portal](../articles/api-key-administration.mdx) for managing
-consumers in the portal.
+consumers under [Services](https://portal.zuplo.com/+/account/project/services)
+in your project.
 
 ## How validation works
 
@@ -76,8 +77,8 @@ when the consumer's key is used. Common uses:
   backend
 - **Organization**: `{"orgId": 456}` for multi-tenant routing
 
-Metadata is set when creating a consumer via the
-[portal](../articles/api-key-administration.mdx),
+Set metadata when creating a consumer via the
+[portal](https://portal.zuplo.com/+/account/project/services),
 [Developer API](../articles/api-key-api.mdx), or
 [developer portal self-serve](#self-serve-key-management).
 
@@ -173,11 +174,11 @@ self-serve API key management. Your API consumers can sign in to the portal and
 create, view, and delete their own keys without contacting your team.
 
 To enable self-serve access, assign a **manager** to a consumer. Managers are
-identified by email and identity provider subject. This can be done in the
-portal, via the [Developer API](../articles/api-key-api.mdx), or automatically
-when a user signs in using
-[Auth0](../dev-portal/dev-portal-create-consumer-on-auth.mdx) or another
-identity provider.
+identified by email and identity provider subject. You can assign a manager in
+the [portal](https://portal.zuplo.com/+/account/project/services), via the
+[Developer API](../articles/api-key-api.mdx), or automatically when a user signs
+in using [Auth0](../dev-portal/dev-portal-create-consumer-on-auth.mdx) or
+another identity provider.
 
 ## Buckets and environments
 

package/docs/concepts/authentication.mdx

@@ -48,8 +48,9 @@ reference.
 
 Zuplo's built-in [API key management](../articles/api-key-management.mdx)
 provides a complete system for issuing, managing, and validating API keys.
-Consumers (API key holders) can be created via the portal, API, or developer
-portal self-serve.
+Create consumers (API key holders) under
+[**Services**](https://portal.zuplo.com/+/account/project/services) in your
+project, via the API, or via developer portal self-serve.
 
 Best for: B2B APIs, developer platforms, and any API where you manage consumer
 access.

package/docs/concepts/source-control-and-deployment.mdx

@@ -210,7 +210,9 @@ The typical workflow from development to production looks like this:
   <DiagramEdge from="merge" to="production" />
 </Diagram>
 
-1. **Develop** locally with `zuplo dev` or in the portal working copy.
+1. **Develop** locally with `zuplo dev` or in your
+   [project's working copy](https://portal.zuplo.com/+/account/project/) in the
+   Zuplo Portal.
 2. **Push** your changes to a feature branch. If using GitHub, a Preview
    environment deploys automatically. If using another provider, your CI/CD
    pipeline runs `zuplo deploy`.

package/docs/dev-portal/documenting-mcp-servers.mdx

@@ -0,0 +1,223 @@
+---
+title: Documenting MCP Servers
+sidebar_label: Documenting MCP Servers
+navigation_icon: bot
+description:
+  Use the x-mcp-server OpenAPI extension to render an MCP setup card in the Dev
+  Portal for external or proxied MCP servers.
+---
+
+The Dev Portal renders a dedicated
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) setup UI for
+any OpenAPI operation that includes the `x-mcp-server` extension. The card
+replaces the standard request/response view with the MCP endpoint URL, a copy
+button, and tabbed installation instructions for Claude, ChatGPT, Cursor, VS
+Code, and a generic config.
+
+:::tip{title="Building an MCP server on Zuplo?"}
+
+If your MCP server uses Zuplo's
+[MCP Server Handler](/docs/handlers/mcp-server.mdx), the `x-mcp-server`
+extension is added to your OpenAPI spec automatically. Skip this guide — there
+is nothing to configure. See the
+[MCP Server overview](/docs/mcp-server/introduction.mdx) for the build path.
+
+:::
+
+## When to use this guide
+
+Use this guide when you want to surface an MCP server in your Dev Portal that
+you are **not** building with Zuplo's MCP Server Handler. Common scenarios:
+
+- You proxy a third-party MCP server through a Zuplo route (for example, with a
+  [URL forward](/docs/handlers/url-forward.mdx) or
+  [custom handler](/docs/handlers/custom-handler.mdx)) and want to publish setup
+  instructions for it.
+- You hand-author an OpenAPI spec for an MCP server hosted outside Zuplo.
+- You catalog multiple MCP servers — some yours, some external — in a single Dev
+  Portal.
+
+In every case, this guide covers only the **documentation** side: how the Dev
+Portal renders the MCP card. Authentication, rate limiting, and any other
+gateway behavior is configured on the underlying route as usual.
+
+## Adding the extension
+
+Add `x-mcp-server` to the operation that represents the MCP endpoint. MCP
+servers typically use `POST`, but the extension works on any HTTP method.
+
+```json title="openapi.json"
+{
+  "paths": {
+    "/mcp": {
+      "post": {
+        "summary": "Acme Docs MCP",
+        "description": "MCP endpoint for searching Acme's documentation.",
+        "operationId": "acmeDocsMcp",
+        "x-mcp-server": {
+          "name": "acme-docs",
+          "version": "1.0.0",
+          "tools": [
+            {
+              "name": "search_docs",
+              "description": "Search the documentation"
+            },
+            {
+              "name": "get_page",
+              "description": "Retrieve a specific documentation page"
+            }
+          ]
+        },
+        "responses": {
+          "200": {
+            "description": "MCP response"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+For a quick setup with no metadata, use the shorthand `"x-mcp-server": true`.
+The operation `summary` is then used as the server name.
+
+## Extension properties
+
+| Property  | Type     | Required | Description                                                                                                          |
+| --------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
+| `name`    | `string` | No       | Display name used in the generated client config snippets. Falls back to the operation `summary`, then `mcp-server`. |
+| `version` | `string` | No       | Version metadata. Included for completeness; not currently rendered in the UI.                                       |
+| `tools`   | `array`  | No       | Tool metadata. Used by Zuplo enrichment; not currently rendered in the UI.                                           |
+
+Each entry in `tools` accepts:
+
+| Property      | Type     | Required | Description                     |
+| ------------- | -------- | -------- | ------------------------------- |
+| `name`        | `string` | Yes      | Tool name                       |
+| `description` | `string` | No       | Human-readable tool description |
+
+## MCP URL resolution
+
+The displayed MCP URL is constructed from the **server URL** of the API plus the
+**path** of the operation. The server URL comes from the OpenAPI `servers` array
+(or the operation-level `servers` override, when present).
+
+For example:
+
+```json
+{
+  "servers": [{ "url": "https://api.example.com" }],
+  "paths": {
+    "/mcp/docs": {
+      "post": {
+        "x-mcp-server": { "name": "docs-mcp" },
+        "responses": { "200": { "description": "OK" } }
+      }
+    }
+  }
+}
+```
+
+The displayed MCP URL is `https://api.example.com/mcp/docs`. Make sure the
+server URL points to wherever the MCP server actually accepts requests — for
+proxied servers, that is typically your Zuplo gateway URL.
+
+## Complete example
+
+This minimal but complete OpenAPI spec produces an MCP endpoint page in the Dev
+Portal:
+
+```json title="mcp-api.json"
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Acme Docs MCP",
+    "version": "1.0.0"
+  },
+  "servers": [
+    {
+      "url": "https://api.example.com",
+      "description": "Production"
+    }
+  ],
+  "paths": {
+    "/mcp": {
+      "post": {
+        "tags": ["MCP"],
+        "summary": "Acme Docs MCP",
+        "description": "MCP endpoint for searching Acme's documentation.",
+        "operationId": "acmeDocsMcp",
+        "x-mcp-server": {
+          "name": "acme-docs",
+          "version": "1.0.0",
+          "tools": [
+            {
+              "name": "search_docs",
+              "description": "Search the documentation"
+            }
+          ]
+        },
+        "responses": {
+          "200": {
+            "description": "MCP response"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Reference the spec from your Dev Portal config (see
+[API Reference](./zudoku/configuration/api-reference.md) for the full `apis`
+configuration):
+
+```tsx title="zudoku.config.tsx"
+import type { ZudokuConfig } from "zudoku";
+
+const config: ZudokuConfig = {
+  apis: [
+    {
+      type: "file",
+      input: "./mcp-api.json",
+      path: "mcp",
+    },
+  ],
+  navigation: [
+    {
+      type: "link",
+      label: "MCP Server",
+      to: "/mcp",
+      icon: "bot",
+    },
+  ],
+};
+
+export default config;
+```
+
+## Generated UI
+
+When the Dev Portal detects `x-mcp-server` on an operation, the page renders:
+
+- **MCP Endpoint card** — the full URL with a copy button.
+- **AI Tool Configuration** tabs with setup instructions for:
+  - **Claude** — add via the Connectors UI or the `claude mcp add` CLI command.
+  - **ChatGPT** — app setup via Settings → Apps → Advanced Settings.
+  - **Cursor** — `mcp.json` configuration (global or project-level).
+  - **VS Code** — `.vscode/mcp.json` with native HTTP transport for GitHub
+    Copilot.
+  - **Generic** — standard `mcp.json` format compatible with most MCP clients.
+
+The standard method badge, request body, parameters, and sidecar panels are
+hidden for MCP endpoints because they use a different interaction model.
+
+## Related
+
+- [`x-mcp-server` extension reference](./zudoku/openapi-extensions/x-mcp-server.md)
+  — the underlying OpenAPI extension.
+- [MCP Server Handler](/docs/handlers/mcp-server.mdx) — build an MCP server on
+  Zuplo (and skip this guide entirely).
+- [MCP Server overview](/docs/mcp-server/introduction.mdx) — concepts,
+  capabilities, and the Zuplo-native build path.

package/docs/dev-portal/zudoku/openapi-extensions/x-mcp-server.md

@@ -101,4 +101,4 @@ The standard method badge, request body, parameters, and sidecar panels are hidd
 endpoints.
 
 For a full walkthrough including Dev Portal configuration, see the
-[Documenting MCP Servers guide](/dev-portal/zudoku/guides/mcp-servers).
+[Documenting MCP Servers guide](/docs/dev-portal/documenting-mcp-servers).

package/docs/guides/canary-routing-for-employees.mdx

@@ -203,7 +203,9 @@ export const percentageCanaryRoutingPolicy: InboundPolicyHandler = async (
 
 ### Environment Variables
 
-Configure your environment variables in the Zuplo dashboard:
+Configure environment variables under the
+[**Environments**](https://portal.zuplo.com/+/account/project/environments) tab
+of your project in the Zuplo Portal:
 
 ```bash
 # List of employee emails or user IDs