zuplo 6.69.10 → 6.70.0

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/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/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

package/docs/guides/user-based-backend-routing.mdx

@@ -77,8 +77,9 @@ export default async function policy(
 }
 ```
 
-When creating API keys in the Zuplo portal, set the metadata to include the
-environment:
+When creating API keys under
+[Services](https://portal.zuplo.com/+/account/project/services) in the Zuplo
+Portal, set the metadata to include the environment:
 
 ```json
 {

package/docs/programmable-api/environment.mdx

@@ -313,12 +313,13 @@ context.log.info("Config loaded", {
 
 ## Setting Environment Variables
 
-Environment variables are set in the Zuplo Portal:
+Set environment variables in the Zuplo Portal:
 
-1. Navigate to your project
-2. Go to Settings → Environment Variables
-3. Add variables for each environment (production, preview, development)
-4. Variables are encrypted at rest and in transit
+1. Open the
+   [**Environments**](https://portal.zuplo.com/+/account/project/environments)
+   tab of your project.
+2. Select an environment and add variables under **Environment Variables**.
+3. Zuplo encrypts variables at rest and in transit.
 
 ## See Also
 

package/docs/programmable-api/zuplo-context.mdx

@@ -89,9 +89,9 @@ context.log.info({
 ### `log`
 
 A logger instance for debugging and monitoring. Logs appear in your log tail in
-the portal and in your integrated log solution (for example Datadog).
-Pre-production environments are typically set to **Info** log level, while
-production is set to **Error**.
+the [Zuplo Portal](https://portal.zuplo.com/+/account/project/) and in your
+integrated log solution (for example Datadog). Pre-production environments are
+typically set to **Info** log level, while production is set to **Error**.
 
 :::tip
 

package/package.json

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