zuplo 7.8.7 → 7.8.8

package/docs/{articles/step-5-dynamic-rate-limiting.mdx → getting-started/gateway/dynamic-rate-limiting/index.mdx}

@@ -1,15 +1,24 @@
 ---
-title: Step 5 - Dynamic Rate Limiting
-sidebar_label: "5 - Dynamic Rate Limiting"
+category: API Management
+showLastModified: false
+suggestEdit: false
+title: Dynamic rate limiting - Portal
+description:
+  Move past a single fixed limit by setting rate limits per customer, so each
+  consumer of your API gets its own quota in the Zuplo Portal.
 ---
 
+<WizardSteps build="gateway" method="portal" step="dynamic-rate-limiting" />
+
+<MethodTabs build="gateway" method="portal" step="dynamic-rate-limiting" />
+
 Fortune favors the bold. In this bonus getting started guide - we'll show you
 how to add dynamic rate limiting to your API.
 
 To follow this tutorial you'll need to have completed
-[Step 1](./step-1-setup-basic-gateway.mdx) for a Zuplo project,
-[Step 2](./step-2-add-rate-limiting.mdx) to add rate limiting to that route, and
-[Step 3](./step-3-add-api-key-auth.mdx) to add API key authentication to that
+[Step 1](../setup-a-basic-gateway/index.mdx) for a Zuplo project,
+[Step 2](../add-rate-limiting/index.mdx) to add rate limiting to that route, and
+[Step 3](../add-api-key-auth/index.mdx) to add API key authentication to that
 same route.
 
 :::info{title="What's Dynamic Rate Limiting?"}
@@ -28,7 +37,7 @@ Let's get started.
 1. Add Consumer Metadata
 
    Let's make our rate-limiting policy more dynamic, based on properties of the
-   customer. [Create a new consumer](./step-3-add-api-key-auth.mdx) (Services ->
+   customer. [Create a new consumer](../add-api-key-auth/index.mdx) (Services ->
    API Key Service -> Configure -> Create Consumer), and in the Metadata field,
    set the following:
 
@@ -47,7 +56,7 @@ Let's get started.
    }
    ```
 
-   ![Customer Metadata](../../public/media/step-3-add-rate-limiting/image-2.png)
+   ![Customer Metadata](../../../../public/media/step-3-add-rate-limiting/image-2.png)
 
    Now that there are users with different `customerType`, this information can
    be used to rate limit them differently.
@@ -58,7 +67,7 @@ Let's get started.
    clicking the `+` next to the **modules** folder and choose new empty module.
    Name the module `rate-limit.ts`.
 
-   ![New module](../../public/media/step-3-add-rate-limiting/image-3.png)
+   ![New module](../../../../public/media/step-3-add-rate-limiting/image-3.png)
 
    :::info{title="What's a Module?"}
 
@@ -109,7 +118,7 @@ Let's get started.
    Now we'll reconfigure the rate-limiting policy to wire up our custom
    function. Find the policy in the **Route Designer** and click **Edit**.
 
-   ![Edit Policy](../../public/media/step-3-add-rate-limiting/image-4.png)
+   ![Edit Policy](../../../../public/media/step-3-add-rate-limiting/image-4.png)
 
    Update the configuration to
 
@@ -138,7 +147,7 @@ Let's get started.
 
    Using the Test modal, you can try your dynamic rate limiting. You can grab
    the key for each consumer from **Services → API Keys → Consumers** where you
-   created them. Like [Step 3](./step-3-add-api-key-auth.mdx), you can fill in
+   created them. Like [Step 3](../add-api-key-auth/index.mdx), you can fill in
    the keys into the `Authorization` header and start making calls until you hit
    your rate limit. Try out the other key and observe the difference in rate
    limits.
@@ -160,9 +169,9 @@ less than an hour.
 ### Next Steps
 
 - Continue exploring our docs to learn about customizing your
-  [Developer Portal](../dev-portal/overview.mdx), or explore our various
+  [Developer Portal](../../../dev-portal/overview.mdx), or explore our various
   [Integrations](https://zuplo.com/integrations)
 - [Grab time](https://zuplo.com/meeting) with the Zuplo team to have your
   questions answered
 - Start generating revenue from your new API with our
-  [Monetization tutorial](./monetization/index.mdx)
+  [Monetization tutorial](../../../articles/monetization/index.mdx)

package/docs/{articles/step-5-dynamic-rate-limiting-local.mdx → getting-started/gateway/dynamic-rate-limiting/local.mdx}

@@ -1,16 +1,25 @@
 ---
-title: Step 5 - Dynamic Rate Limiting
-sidebar_label: "5 - Dynamic Rate Limiting"
+category: API Management
+showLastModified: false
+suggestEdit: false
+title: Dynamic rate limiting - Editor
+description:
+  Move past a single fixed limit by setting rate limits per customer, so each
+  consumer of your API gets its own quota with the Zuplo CLI and your editor.
 ---
 
+<WizardSteps build="gateway" method="local" step="dynamic-rate-limiting" />
+
+<MethodTabs build="gateway" method="local" step="dynamic-rate-limiting" />
+
 Fortune favors the bold. In this bonus getting started guide we'll show you how
 to add dynamic rate limiting to your API, all from your local project.
 
 To follow this tutorial you'll need to have completed
-[Step 1](./step-1-setup-basic-gateway-local.mdx) for a Zuplo project,
-[Step 2](./step-2-add-rate-limiting-local.mdx) to add rate limiting to a route,
-and [Step 3](./step-3-add-api-key-auth-local.mdx) to add API key authentication
-to that same route.
+[Step 1](../setup-a-basic-gateway/local.mdx) for a Zuplo project,
+[Step 2](../add-rate-limiting/local.mdx) to add rate limiting to a route, and
+[Step 3](../add-api-key-auth/local.mdx) to add API key authentication to that
+same route.
 
 :::info{title="What's Dynamic Rate Limiting?"}
 
@@ -29,8 +38,8 @@ Let's get started.
 
    Let's make our rate-limiting policy more dynamic, based on properties of the
    customer. In the Zuplo Portal,
-   [create a new consumer](./step-3-add-api-key-auth-local.mdx) (Services → API
-   Key Service → Configure → Create Consumer), and in the Metadata field set the
+   [create a new consumer](../add-api-key-auth/local.mdx) (Services → API Key
+   Service → Configure → Create Consumer), and in the Metadata field set the
    following:
 
    ```json
@@ -132,8 +141,8 @@ Let's get started.
    :::tip
 
    Dynamic rate limiting reads from `request.user`, so the API key
-   authentication policy from [Step 3](./step-3-add-api-key-auth-local.mdx) must
-   run **before** the rate-limiting policy.
+   authentication policy from [Step 3](../add-api-key-auth/local.mdx) must run
+   **before** the rate-limiting policy.
 
    :::
 
@@ -172,9 +181,9 @@ less than an hour.
 ### Next Steps
 
 - Continue exploring our docs to learn about customizing your
-  [Developer Portal](../dev-portal/overview.mdx), or explore our various
+  [Developer Portal](../../../dev-portal/overview.mdx), or explore our various
   [Integrations](https://zuplo.com/integrations)
 - [Grab time](https://zuplo.com/meeting) with the Zuplo team to have your
   questions answered
 - Start generating revenue from your new API with our
-  [Monetization tutorial](./monetization/index.mdx)
+  [Monetization tutorial](../../../articles/monetization/index.mdx)

package/docs/getting-started/gateway/index.mdx

@@ -0,0 +1,24 @@
+---
+category: API Management
+fullWidth: true
+disablePager: true
+showLastModified: false
+suggestEdit: false
+centered: false
+toc: false
+title: Getting Started with API Gateway
+description:
+  Put a managed gateway in front of any REST API with Zuplo, in the Portal,
+  locally with the CLI, or with an AI agent.
+---
+
+<WizardSteps build="gateway" />
+
+An API gateway sits between your clients and your backend. Use it to
+authenticate requests and apply rate limits before traffic reaches your API.
+
+This tutorial starts with a sample backend and takes you through routing,
+policies, and deployment. Choose a workflow to begin. You need a GitHub account
+when you reach the deployment step.
+
+<MethodPicker build="gateway" />

package/docs/{articles/step-1-setup-basic-gateway.mdx → getting-started/gateway/setup-a-basic-gateway/index.mdx}

@@ -1,33 +1,45 @@
 ---
-title: Step 1 - Setup a Basic Gateway
-sidebar_label: "1 - Setup Your Gateway"
+category: API Management
+showLastModified: false
+suggestEdit: false
+title: Setup a basic gateway - Portal
+description:
+  Proxy an origin API through a managed Zuplo gateway, add your first route, and
+  see traffic flowing end to end in the Zuplo Portal.
 ---
 
-<QuickstartPicker
-  mode="portal"
-  alternateLink="/articles/step-1-setup-basic-gateway-local"
-/>
+<WizardSteps build="gateway" method="portal" step="setup-a-basic-gateway" />
+
+<MethodTabs build="gateway" method="portal" step="setup-a-basic-gateway" />
 
 In this tutorial we'll set up a simple gateway. We'll use a simple origin API at
 [echo.zuplo.io](https://echo.zuplo.io).
 
 Note - Zuplo also supports building and running your API locally. To learn more
-[see the documentation](./local-development.mdx).
+[see the documentation](../../../articles/local-development.mdx).
 
 <Stepper>
 
 1. **Sign-in**
 
-   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...
+   Sign in to the Zuplo Portal and create a free account. Open
+   [**Projects**](https://portal.zuplo.com/+/account/projects), click **New
+   Project**, select **API & MCP Gateway**, enter `example-project`, and click
+   **Create Project**. Choose a blank project rather than importing one; this
+   tutorial connects Git later.
+
+   <ModalScreenshot>
+
+   ![New Zuplo project dialog with API & MCP Gateway selected](/media/mcp-gateway-portal-quickstart/new-project.png)
+
+   </ModalScreenshot>
 
 1. Add your first **Route**
 
    Inside your new project, select the **Code** tab (1), choose the
    `routes.oas.json` file (2) and click **Add Route** (3)
 
-   ![Add Route](../../public/media/step-1-setup-basic-gateway/add-route.png)
+   ![Add Route](../../../../public/media/step-1-setup-basic-gateway/add-route.png)
 
    Your API's first route will appear, with many options. First we'll configure
    the route to match specific incoming requests to the gateway:
@@ -38,11 +50,11 @@ Note - Zuplo also supports building and running your API locally. To learn more
    Then we'll specify how the route will invoke the backend origin API, using a
    forward handler:
    - **Request Handler**: We'll use the
-     [URL Forward Handler](../handlers/url-forward.mdx) which proxies requests
-     by "Forwarding to" the same path on specified URL. In this case, enter
-     `https://echo.zuplo.io`
+     [URL Forward Handler](../../../handlers/url-forward.mdx) which proxies
+     requests by "Forwarding to" the same path on specified URL. In this case,
+     enter `https://echo.zuplo.io`
 
-   ![Your First Route](../../public/media/step-1-setup-basic-gateway/image-14.png)
+   ![Your First Route](../../../../public/media/step-1-setup-basic-gateway/image-14.png)
 
    **Save your changes** - click **Save** at the bottom left, or press **CMD+S**
 
@@ -54,7 +66,7 @@ Note - Zuplo also supports building and running your API locally. To learn more
 
    <ModalScreenshot>
 
-   ![Test your API](../../public/media/step-1-setup-basic-gateway/image-15.png)
+   ![Test your API](../../../../public/media/step-1-setup-basic-gateway/image-15.png)
 
    </ModalScreenshot>
 
@@ -89,12 +101,12 @@ Note - Zuplo also supports building and running your API locally. To learn more
    setting the value to `${env.BASE_URL}`. We will set the value for `BASE_URL`
    next.
 
-   ![BASE_URL from Environment](../../public/media/step-1-setup-basic-gateway/image-8.png)
+   ![BASE_URL from Environment](../../../../public/media/step-1-setup-basic-gateway/image-8.png)
 
    Navigate to your project's **Settings** (1) via the navigation bar. Next,
    click **Environment Variables** (2) under Project Settings.
 
-   ![Click Environment Variables](../../public/media/step-1-setup-basic-gateway/set-env-var.png)
+   ![Click Environment Variables](../../../../public/media/step-1-setup-basic-gateway/set-env-var.png)
 
    Add an Environment Variable (3) called `BASE_URL`. Leave the "Secret"
    checkbox unchecked. This is typically not a secret, so there's no need to
@@ -102,7 +114,7 @@ Note - Zuplo also supports building and running your API locally. To learn more
 
    <ModalScreenshot>
 
-   ![BASE_URL Environment Variable](../../public/media/step-1-setup-basic-gateway/env-var.png)
+   ![BASE_URL Environment Variable](../../../../public/media/step-1-setup-basic-gateway/env-var.png)
 
    </ModalScreenshot>
 
@@ -111,6 +123,3 @@ Note - Zuplo also supports building and running your API locally. To learn more
    response from Step 2.
 
 </Stepper>
-
-**NEXT** Try
-[Step 2 - Add Rate Limiting to your API](./step-2-add-rate-limiting.mdx).

package/docs/{articles/step-1-setup-basic-gateway-local.mdx → getting-started/gateway/setup-a-basic-gateway/local.mdx}

@@ -1,26 +1,33 @@
 ---
-title: Step 1 - Setup a Basic Gateway
-sidebar_label: "1 - Setup Your Gateway"
+category: API Management
+showLastModified: false
+suggestEdit: false
+title: Setup a basic gateway - Editor
+description:
+  Proxy an origin API through a managed Zuplo gateway, add your first route, and
+  see traffic flowing end to end with the Zuplo CLI and your editor.
 ---
 
-<QuickstartPicker
-  mode="local"
-  alternateLink="/articles/step-1-setup-basic-gateway"
-/>
+<WizardSteps build="gateway" method="local" step="setup-a-basic-gateway" />
+
+<MethodTabs build="gateway" method="local" step="setup-a-basic-gateway" />
 
 In this tutorial we'll set up a simple gateway using Zuplo's local development,
-powered by the [Zuplo CLI](../cli/overview.mdx). We'll use the default project
-template, which ships with a working todo API.
+powered by the [Zuplo CLI](../../../cli/overview.mdx). We'll use the default
+project template, which ships with a working todo API.
 
 ## Requirements
 
 - [Node.js](https://nodejs.org/en/download) 24.0.0 or higher
 
+## Create and test your gateway
+
 <Stepper>
 
 1. **Create your project**
 
-   Create a new project with [create-zuplo-api](../cli/create-zuplo-api.mdx):
+   Create a new project with
+   [create-zuplo-api](../../../cli/create-zuplo-api.mdx):
 
    ```bash
    npx create-zuplo-api@latest
@@ -86,10 +93,12 @@ template, which ships with a working todo API.
    (`GET /todos`, `POST /todos`, `PUT /todos/{id}`, `DELETE /todos/{id}`)
    defined in `config/routes.oas.json`.
 
-   Open the [local Route Designer](./local-development-routes-designer.mdx) at
-   http://localhost:9100 — you can also click the link printed in the terminal —
-   to see the routes. Select **Get all todos** to inspect how it's configured;
-   you can change the path, method, request handler, and add policies from here.
+   Open the
+   [local Route Designer](../../../articles/local-development-routes-designer.mdx)
+   at http://localhost:9100 — you can also click the link printed in the
+   terminal — to see the routes. Select **Get all todos** to inspect how it's
+   configured; you can change the path, method, request handler, and add
+   policies from here.
 
 1. **Test the API**
 
@@ -107,6 +116,3 @@ template, which ships with a working todo API.
    gateway is now serving traffic locally.
 
 </Stepper>
-
-**NEXT** Try
-[Step 2 - Add Rate Limiting to your API](./step-2-add-rate-limiting-local.mdx).

package/docs/getting-started/index.mdx

@@ -0,0 +1,25 @@
+---
+category: Getting Started
+fullWidth: true
+disablePager: true
+showLastModified: false
+suggestEdit: false
+centered: false
+toc: false
+title: What do you want to build?
+description:
+  Pick what to build with Zuplo, choose how you want to build it, and follow a
+  step-by-step tutorial.
+---
+
+<WizardSteps />
+
+Create your first working project with Zuplo. Choose what you want to build,
+then select a workflow and follow a guided tutorial with a sample API or
+service.
+
+Start with the product that fits your task. Most tutorials offer the Zuplo
+Portal, a local editor, or an AI coding agent. The AI Gateway tutorial takes you
+directly to setup in the Portal.
+
+<BuildPicker />

package/docs/getting-started/mcp-gateway/agent.mdx

@@ -0,0 +1,161 @@
+---
+category: MCP Gateway
+showLastModified: false
+suggestEdit: false
+sidebar_label: Agent
+title: Getting Started with MCP Gateway - Agent
+description:
+  Build a local MCP Gateway with a coding agent, authorize Linear through OAuth,
+  and verify a real tool call before deploying.
+---
+
+<WizardSteps build="mcp-gateway" method="agent" />
+
+<MethodTabs build="mcp-gateway" method="agent" />
+
+Have a coding agent build a local MCP Gateway in front of Linear. You'll
+complete the browser authorization yourself and verify a real Linear tool call.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/en/download) 24 or later.
+- A [Zuplo account](https://portal.zuplo.com).
+- An installed coding agent and a Linear account with access to a workspace.
+- An MCP client that can connect to a local HTTP server and complete OAuth.
+
+This tutorial uses Zuplo's local `dev-login` shortcut. For a hosted gateway with
+your identity provider, use the [Portal tutorial](./portal.mdx).
+
+## Build your MCP Gateway with an agent
+
+<Stepper>
+
+1. **Create your project**
+
+   Run:
+
+   ```bash
+   npx create-zuplo-api@latest linear-mcp-gateway
+   cd linear-mcp-gateway
+   ```
+
+   When prompted, choose **Yes** to create a matching Portal project, complete
+   sign-in, and select your Zuplo account. Select the coding agent you use when
+   asked. The CLI creates and links the hosted project. See
+   [`create-zuplo-api`](../../cli/create-zuplo-api.mdx).
+
+   :::tip{title="Zuplo skills"}
+
+   The scaffold installs Zuplo skills in this project for Codex and Cursor and
+   configures the Claude Code plugin. If setup fails, follow
+   [Agent Skills](../../build-with-ai.mdx#agent-skills) from this directory
+   before starting your agent.
+
+   :::
+
+2. **Give the agent the gateway configuration task**
+
+   Open your agent in the project directory and use this prompt:
+
+   ```text
+   Read the project instructions and bundled Zuplo MCP Gateway docs. Build a
+   local gateway in front of Linear using the dev-login shortcut. Use
+   http://127.0.0.1:9000 consistently for local URLs.
+
+   In modules/zuplo.runtime.ts, export runtimeInit(runtime: RuntimeExtensions),
+   import RuntimeExtensions from @zuplo/runtime and McpGatewayPlugin from
+   @zuplo/runtime/mcp-gateway, and register new McpGatewayPlugin().
+
+   config/policies.json must be an object containing a policies array. Add:
+
+   1. name "dev-oauth", policyType "mcp-oauth-inbound", handler module
+      "$import(@zuplo/runtime/mcp-gateway)", export "McpOAuthInboundPolicy".
+      options.oidc has issuer "http://127.0.0.1:9000" and jwksUrl
+      "http://127.0.0.1:9000/jwks". options.browserLogin.url is
+      "http://127.0.0.1:9000/__zuplo/oauth/dev-login".
+      The OIDC values are placeholders required for local dev-login; don't
+      create a JWKS route or claim that /jwks exists.
+
+   2. name "mcp-token-exchange-linear", policyType "mcp-token-exchange-inbound",
+      handler module "$import(@zuplo/runtime/mcp-gateway)", export
+      "McpTokenExchangeInboundPolicy". Its options are:
+      {
+        "displayName": "Linear",
+        "protectedResourceMetadataUrl": "https://mcp.linear.app/.well-known/oauth-protected-resource",
+        "authMode": "user-oauth",
+        "scopes": [],
+        "clientRegistration": { "mode": "auto" }
+      }
+
+   In config/routes.oas.json, add /mcp/linear-v1 with method key "get,post",
+   operationId "linear-mcp-server", and x-zuplo-route.corsPolicy "none".
+   Use McpProxyHandler from $import(@zuplo/runtime/mcp-gateway), with options
+   { "rewritePattern": "https://mcp.linear.app/mcp" }.
+   Attach inbound policies in this order: dev-oauth, mcp-token-exchange-linear.
+
+   Run npm run dev and send an unauthenticated tools/list POST to the route.
+   Verify 401 and a WWW-Authenticate header identifying the protected-resource
+   metadata URL. This is only the first check; do not claim Linear works until
+   I complete browser OAuth and run a real tool. Do not deploy dev-login.
+   Show me the diff and the client URL.
+   ```
+
+   The [Editor tutorial](./local.mdx) shows these files as copyable examples.
+   See [How it works](../../mcp-gateway/how-it-works.mdx) for the gateway's
+   sign-in and upstream authorization flows.
+
+3. **Verify authentication is attached**
+
+   Review the diff, then run `npm run dev` if it isn't already running. In
+   another terminal, send:
+
+   ```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}'
+   ```
+
+   Expect `401 Unauthorized` and a `WWW-Authenticate` header pointing to
+   `/.well-known/oauth-protected-resource/mcp/linear-v1`. A `404` suggests a
+   route mismatch; for a `500`, inspect the gateway's terminal output.
+
+4. **Authorize Linear in your MCP client**
+
+   Add `http://127.0.0.1:9000/mcp/linear-v1` as an HTTP MCP server in your
+   client. See
+   [Connect MCP clients](../../mcp-gateway/connect-clients/overview.mdx) for
+   client-specific setup.
+
+   Keep `127.0.0.1` in the client URL to match the policy. During the browser
+   OAuth flow, dev-login signs you in locally. On the gateway's consent page,
+   click **Connect** for Linear, authorize your Linear account, then click
+   **Authorize** to complete the gateway connection.
+
+   Complete these actions yourself; the coding agent doesn't need your Linear
+   password or tokens.
+
+5. **Run a real tool**
+
+   Ask your client to `List my open Linear issues`. Approve the tool call. Check
+   that it returns your issues, or an empty result if you have none, without an
+   authentication error.
+
+   If connection fails, check that the local server is running and the client
+   uses `127.0.0.1` throughout. See
+   [Local development](../../mcp-gateway/code-config/local-development.mdx).
+
+</Stepper>
+
+## Deploy with your identity provider
+
+Dev-login works only on loopback origins. Before sharing the gateway, replace it
+with your identity provider using
+[Configure local and deployed environments](../../mcp-gateway/code-config/local-development.mdx#configure-local-and-deployed-environments),
+then follow [Deploy to the edge](../gateway/deploy-to-the-edge/local.mdx).
+Repeat the full browser authorization and tool call against the hosted URL.
+
+## Next steps
+
+- [Front more upstream servers](../../mcp-gateway/code-config/multi-upstream.mdx).
+- [Filter tools and other capabilities](../../mcp-gateway/capability-filtering.mdx).
+- [Choose an identity provider](../../mcp-gateway/auth/overview.mdx).

package/docs/getting-started/mcp-gateway/index.mdx

@@ -0,0 +1,25 @@
+---
+category: MCP Gateway
+fullWidth: true
+disablePager: true
+showLastModified: false
+suggestEdit: false
+centered: false
+toc: false
+title: Getting Started with MCP Gateway
+description:
+  Govern remote MCP servers with auth, tool curation and policies with Zuplo, in
+  the Portal, locally with the CLI, or with an AI agent.
+---
+
+<WizardSteps build="mcp-gateway" />
+
+An MCP Gateway controls access to an existing Model Context Protocol (MCP)
+server. This tutorial connects Linear through Zuplo so an AI assistant can call
+its tools after you sign in.
+
+You need a Linear workspace and an MCP client, such as Claude Desktop. The
+Portal guide uses Auth0 for sign-in; the local guides use development sign-in to
+test on your machine. Choose the workflow that fits your setup.
+
+<MethodPicker build="mcp-gateway" />