zuplo 7.8.7 → 7.8.9

package/docs/getting-started/migrate/agent.mdx

@@ -0,0 +1,129 @@
+---
+category: Migration Guides
+showLastModified: false
+suggestEdit: false
+sidebar_label: Agent
+title: Getting Started with API Migration - Agent
+description:
+  Use a coding agent to import an OpenAPI document and configure upstream
+  forwarding, then review and test the API before migrating clients.
+---
+
+<WizardSteps build="migrate" method="agent" />
+
+<MethodTabs build="migrate" method="agent" />
+
+Have a coding agent import an existing API and configure Zuplo to forward its
+requests. You'll review the route changes and verify responses before moving any
+clients.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/en/download) 24 or later and Git.
+- A [Zuplo account](https://portal.zuplo.com) and an installed coding agent.
+- Your API's OpenAPI document and upstream URL, or the Petstore document linked
+  below.
+
+## Migrate your API with an agent
+
+<Stepper>
+
+1. **Create the migration project**
+
+   Run:
+
+   ```bash
+   npx create-zuplo-api@latest migrated-api
+   cd migrated-api
+   ```
+
+   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. **Get your existing OpenAPI document**
+
+   Get your API's OpenAPI document from its repository, API documentation, or
+   current gateway and save a copy in the project root. The prompt below uses
+   `openapi.json`; substitute your file's name if it differs.
+
+   <p>
+     If you don't have an OpenAPI document, download the{" "}
+     <a href="/docs/downloads/petstore-openapi.json" download="openapi.json">
+       Swagger Petstore OpenAPI document
+     </a>
+     .
+   </p>
+
+   Give the agent your upstream URL and current authentication requirements.
+   Choose a read-only operation to verify. For Petstore, use
+   `https://petstore3.swagger.io/api/v3/pet/findByStatus?status=available`.
+
+3. **Give the agent a bounded migration task**
+
+   Open the agent in the project directory. Provide the upstream URL and
+   operation you chose, then use this prompt:
+
+   ```text
+   Read the project instructions and bundled Zuplo docs. Import ./openapi.json
+   into ./config/routes.oas.json with:
+   npx zuplo openapi merge --source ./openapi.json --destination ./config/routes.oas.json
+
+   For the read-only operation I selected, configure x-zuplo-route with a
+   urlForwardHandler from $import(@zuplo/runtime). Set options.baseUrl to my
+   original API's base URL. Check imported paths so server URL prefixes are
+   not duplicated. Preserve the operationId and unrelated route configuration.
+
+   Start npm run dev. Call the original API and the matching localhost:9000
+   route with the same query parameters and required headers. Compare their
+   status codes and response structure, allowing for changes in live data.
+   Show the diff and report actual test results, including failures.
+
+   Do not delete other routes, change client URLs or DNS, add credentials to
+   source files, or deploy. Identify any imported paths, security declarations,
+   or server URL prefixes that need manual review. For private APIs, OpenAPI
+   security metadata is not a substitute for gateway authentication policies.
+   ```
+
+   Ask the agent to preserve your existing authentication, rate limits, and
+   transformations explicitly; don't infer them from the OpenAPI file alone.
+
+4. **Review and verify the migration**
+
+   Check that the handler points to the original API, that server-path prefixes
+   aren't duplicated, and that unrelated routes remain intact. Review `git diff`
+   before accepting the agent's changes.
+
+   With `npm run dev` running, call your chosen operation directly and through
+   the local gateway. Use the same headers and query parameters in both
+   requests, and compare the status and response structure. For a private API,
+   also test invalid or missing credentials and the request bodies and error
+   responses that clients depend on.
+
+5. **Deploy and move traffic gradually**
+
+   Follow [Deploy to the edge](../gateway/deploy-to-the-edge/local.mdx). Repeat
+   the tests against the deployed gateway URL, then point one test client at it.
+   Keep the original endpoint available while migrating clients in stages so you
+   can restore their previous base URL if needed.
+
+</Stepper>
+
+## Next steps
+
+- [Editor tutorial](./local.mdx) for the exact route configuration and update
+  workflow.
+- [Migration overview](../../articles/migration-overview.md) for translating
+  another gateway's configuration.
+- [API key authentication](../gateway/add-api-key-auth/local.mdx) to protect
+  routes with managed keys.

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

@@ -0,0 +1,25 @@
+---
+category: Migration Guides
+fullWidth: true
+disablePager: true
+showLastModified: false
+suggestEdit: false
+centered: false
+toc: false
+title: Getting Started with API Migration
+description:
+  Import an OpenAPI document, route requests through Zuplo, and compare them
+  with your existing backend in the Portal, locally, or with an AI agent.
+---
+
+<WizardSteps build="migrate" />
+
+Put Zuplo in front of your existing API by importing its OpenAPI document and
+forwarding requests to your backend. This tutorial helps you verify the gateway
+before you change where your clients send traffic.
+
+Bring your OpenAPI document and backend URL, or use the included Petstore
+example. Choose a workflow to import the API and compare a read-only request
+through Zuplo with the same request sent directly to your backend.
+
+<MethodPicker build="migrate" />

package/docs/getting-started/migrate/local.mdx

@@ -0,0 +1,141 @@
+---
+category: Migration Guides
+showLastModified: false
+suggestEdit: false
+sidebar_label: Editor
+title: Getting Started with API Migration - Editor
+description:
+  Import an existing API into a local Zuplo project, configure upstream
+  forwarding, compare responses, and deploy for a gradual migration.
+---
+
+<WizardSteps build="migrate" method="local" />
+
+<MethodTabs build="migrate" method="local" />
+
+Import an existing API into a local Zuplo project, add its upstream handler, and
+compare responses before moving client traffic.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/en/download) 24 or later and Git.
+- A terminal and an editor.
+- A [Zuplo account](https://portal.zuplo.com) for linking and deployment.
+
+## Import and test your API
+
+<Stepper>
+
+1. **Create a project**
+
+   Run:
+
+   ```bash
+   npx create-zuplo-api@latest migrated-api
+   cd migrated-api
+   ```
+
+   When prompted, choose **Yes** to create a matching Portal project, then
+   complete sign-in and account selection to link your local copy. For an
+   existing project, work on a new Git branch before importing routes.
+
+2. **Get your existing OpenAPI document**
+
+   Get your API's OpenAPI document from its repository, API documentation, or
+   current gateway. Save a copy in the project root. The commands below use
+   `openapi.json`; substitute your file's name if it differs.
+
+   <p>
+     If you don't have an OpenAPI document, download the{" "}
+     <a href="/docs/downloads/petstore-openapi.json" download="openapi.json">
+       Swagger Petstore OpenAPI document
+     </a>
+     .
+   </p>
+
+   Choose a read-only operation and call it directly on the original API. Record
+   its URL, required headers, query parameters, and response. For Petstore, try:
+
+   ```bash
+   curl -i "https://petstore3.swagger.io/api/v3/pet/findByStatus?status=available"
+   ```
+
+3. **Import the routes**
+
+   Run:
+
+   ```bash
+   npx zuplo openapi merge --source ./openapi.json --destination ./config/routes.oas.json
+   ```
+
+   Open `config/routes.oas.json` and find the operation you chose. The
+   destination must end in `.oas.json`. See
+   [`openapi merge`](../../cli/openapi-merge.mdx) for importing from URLs and
+   controlling server paths.
+
+4. **Configure forwarding**
+
+   On the operation you chose, set `x-zuplo-route` to the following, replacing
+   `YOUR_UPSTREAM_BASE_URL` with your original API's base URL:
+
+   ```json
+   "x-zuplo-route": {
+     "corsPolicy": "none",
+     "handler": {
+       "module": "$import(@zuplo/runtime)",
+       "export": "urlForwardHandler",
+       "options": { "baseUrl": "YOUR_UPSTREAM_BASE_URL" }
+     },
+     "policies": { "inbound": [] }
+   }
+   ```
+
+   Importing OpenAPI describes the route; this handler makes it forward to the
+   upstream. See [URL Forward](../../handlers/url-forward.mdx). Check the
+   imported path so any server prefix appears only once. For Petstore, use
+   `https://petstore3.swagger.io/api/v3` if the route path is
+   `/pet/findByStatus`, or `https://petstore3.swagger.io` if it already starts
+   with `/api/v3`.
+
+5. **Compare local and upstream responses**
+
+   Start `npm run dev`. In a second terminal, run:
+
+   ```bash
+   curl -i "http://localhost:9000/YOUR_ROUTE"
+   ```
+
+   Replace `YOUR_ROUTE` with the imported route path. Include the same headers
+   and query parameters as your original request, such as `status=available` for
+   Petstore. Compare the status and response structure with the original API;
+   live data can change between requests. Check the gateway logs if you get an
+   error.
+
+6. **Preserve behavior when importing updates**
+
+   Before re-importing a changed OpenAPI file, commit your work. Run the same
+   merge command and review `git diff`. The importer merges routes by path and
+   method and preserves Zuplo route configuration. Routes absent from the new
+   document aren't automatically deleted; review them explicitly.
+
+   For your own API, translate authentication, rate limits, and transformations
+   into Zuplo policies. OpenAPI security declarations don't enforce access
+   control. Test both allowed and rejected requests, plus the headers, query
+   parameters, and bodies your clients send. The
+   [migration overview](../../articles/migration-overview.md) covers existing
+   gateway configurations.
+
+7. **Deploy and move a test client**
+
+   Follow [Deploy to the edge](../gateway/deploy-to-the-edge/local.mdx), then
+   repeat your tests against the deployed gateway URL. Change one test client's
+   base URL to that gateway and verify its workflow before moving more clients.
+   Keep the original endpoint available for rollback.
+
+</Stepper>
+
+## Next steps
+
+- [Add API key authentication](../gateway/add-api-key-auth/local.mdx).
+- [Configure upstream AWS authentication](../../articles/upstream-iam-auth.mdx).
+- [Plan your full migration](../../articles/migration-overview.md).

package/docs/getting-started/migrate/portal.mdx

@@ -0,0 +1,129 @@
+---
+category: Migration Guides
+showLastModified: false
+suggestEdit: false
+sidebar_label: Portal
+title: Getting Started with API Migration - Portal
+description:
+  Import an OpenAPI document in the Portal, forward requests to your existing
+  API, and verify a route before moving client traffic.
+---
+
+<WizardSteps build="migrate" method="portal" />
+
+<MethodTabs build="migrate" method="portal" />
+
+Put Zuplo in front of an existing API by importing its OpenAPI document and
+forwarding requests to the original backend. You'll test one read-only route
+before changing any client traffic.
+
+## Prerequisites
+
+- A [Zuplo account](https://portal.zuplo.com).
+- Your existing API's OpenAPI document in JSON or YAML and its upstream URL.
+
+## Get your existing OpenAPI document
+
+Get the OpenAPI document for the API you want to migrate from its repository,
+API documentation, or current gateway. Download or export the existing file; you
+don't need to write a new one for this tutorial.
+
+<p>
+  If you don't have an OpenAPI document, download the{" "}
+  <a href="/docs/downloads/petstore-openapi.json" download="openapi.json">
+    Swagger Petstore OpenAPI document
+  </a>
+  .
+</p>
+
+Choose a read-only operation and call it directly on the original API. You'll
+compare that response with the gateway's response. For Petstore, you can use
+[`GET /pet/findByStatus?status=available`](https://petstore3.swagger.io/api/v3/pet/findByStatus?status=available).
+
+## Import and test a route
+
+<Stepper>
+
+1. **Create the gateway**
+
+   In [**Projects**](https://portal.zuplo.com/+/account/projects), click **New
+   Project**, select **API & MCP Gateway**, enter `migrated-api`, and click
+   **Create Project**.
+
+2. **Import the document**
+
+   Open **Code → config/routes.oas.json** and click **Import OpenAPI**. Upload
+   your OpenAPI file, review the routes, and click **Complete Import**.
+
+   <ModalScreenshot>
+
+   ![Import an OpenAPI file in the Route Designer](/media/mcp-quickstart/import-openapi.png)
+
+   </ModalScreenshot>
+
+   The Route Designer should now list your API's routes. Importing an API
+   description doesn't configure its forwarding behavior or enforce its security
+   requirements; configure those next.
+
+3. **Set the upstream handler**
+
+   Select the read-only route you chose. Under **Request Handler**, select **URL
+   Forward** and set **Forward to** to your original API's base URL. Save your
+   changes.
+
+   The [URL Forward handler](../../handlers/url-forward.mdx) appends the request
+   path. Check the imported path before setting the base URL so that any server
+   prefix appears only once. For Petstore, use
+   `https://petstore3.swagger.io/api/v3` if the route path is
+   `/pet/findByStatus`, or `https://petstore3.swagger.io` if the imported path
+   already starts with `/api/v3`.
+
+4. **Compare the response**
+
+   Click **Test** next to the route's path, then send a GET request. Expect the
+   same status and response structure as the original API. Include the same
+   query parameters, such as `status=available` for the Petstore example.
+
+   Copy the gateway request URL from the test dialog and call it from a terminal
+   too:
+
+   ```bash
+   curl -i "https://YOUR_GATEWAY.zuplo.app/YOUR_ROUTE"
+   ```
+
+   Replace `YOUR_ROUTE` with the imported route path and include its query
+   parameters and any required headers. A `404` usually means the route or
+   upstream path differs from the imported path. If forwarding fails, recheck
+   the handler's upstream URL.
+
+5. **Preserve your API's behavior**
+
+   For a private API, add the
+   [authentication policies](../../articles/api-key-authentication.mdx) your
+   clients require and configure any credentials the upstream requires. OpenAPI
+   `security` metadata alone doesn't enforce authentication in Zuplo.
+
+   Before migrating real traffic, verify successful and failed requests, query
+   parameters, headers, request bodies, and status codes. Recreate any rate
+   limits or transformations currently handled by your old gateway. See the
+   [migration overview](../../articles/migration-overview.md) for
+   platform-specific migration guides.
+
+6. **Deploy and move a test client**
+
+   Follow [Deploy to the edge](../gateway/deploy-to-the-edge/index.mdx) to
+   connect source control and deploy. Repeat your tests using the deployed
+   gateway URL.
+
+   Change one test client's base URL to the gateway and verify its normal
+   workflow. Keep the old endpoint available while you move clients in stages;
+   roll that client back to its previous base URL if checks fail. Move your
+   production domain only after the gateway passes your migration checks.
+
+</Stepper>
+
+## Next steps
+
+- [Add API key authentication](../gateway/add-api-key-auth/index.mdx).
+- [Import updated OpenAPI documents](../../articles/openapi.mdx).
+- [Plan a migration from another gateway](../../articles/migration-overview.md).

package/docs/home.mdx

@@ -1,6 +1,12 @@
 ---
 title: Zuplo Documentation
 sidebar_label: Home
+fullWidth: true
+centered: false
+toc: false
+disablePager: true
+showLastModified: false
+suggestEdit: false
 ---
 
 <DocsHome />

package/docs/mcp-gateway/connect-clients/chatgpt.mdx

@@ -30,7 +30,8 @@ article for the latest plan availability.
 ## Prerequisites
 
 - A Zuplo project with the MCP Gateway plugin configured and at least one MCP
-  route. See the [quickstart](../quickstart.mdx) if you haven't set one up yet.
+  route. See the [quickstart](../../getting-started/mcp-gateway/portal.mdx) if
+  you haven't set one up yet.
 - A ChatGPT Business, Enterprise, or Edu workspace for full MCP apps. Pro users
   can use read/fetch MCP servers only.
 - Developer Mode enabled for the ChatGPT account or workspace. OpenAI's current

package/docs/mcp-gateway/connect-clients/claude-code.mdx

@@ -14,7 +14,8 @@ OAuth flow against the gateway in your browser.
 ## Prerequisites
 
 - A Zuplo project with the MCP Gateway plugin configured and at least one MCP
-  route. See the [quickstart](../quickstart.mdx) if you haven't set one up yet.
+  route. See the [quickstart](../../getting-started/mcp-gateway/portal.mdx) if
+  you haven't set one up yet.
 - Claude Code installed and signed in. Install instructions are at
   [code.claude.com](https://code.claude.com/).
 

package/docs/mcp-gateway/connect-clients/claude-desktop.mdx

@@ -13,7 +13,8 @@ Claude's connector settings, then complete the browser-based OAuth flow.
 ## Prerequisites
 
 - A Zuplo project with the MCP Gateway plugin configured and at least one MCP
-  route. See the [quickstart](../quickstart.mdx) if you haven't set one up yet.
+  route. See the [quickstart](../../getting-started/mcp-gateway/portal.mdx) if
+  you haven't set one up yet.
 - Claude Desktop installed, or access to Claude.ai in your browser.
 - A Claude plan that supports custom connectors. Per
   [Anthropic's documentation](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp),
@@ -25,9 +26,13 @@ Claude's connector settings, then complete the browser-based OAuth flow.
 ## Get the route URL
 
 Each MCP route in `config/routes.oas.json` is reachable at
-`https://{deploymentUrl}/{routePath}` once deployed (or
-`http://127.0.0.1:9000/{routePath}` when running locally with `zuplo dev`). The
-`{routePath}` is the path you set on the route — for example `/mcp/linear-v1`.
+`https://{deploymentUrl}/{routePath}` once deployed. The `{routePath}` is the
+path you set on the route — for example `/mcp/linear-v1`.
+
+Native remote connectors connect from Anthropic's servers, so the gateway URL
+must be reachable from those servers. For a gateway running locally with
+`zuplo dev`, use the [manual configuration](#use-a-manual-config-file-advanced)
+with `http://127.0.0.1:9000/{routePath}`.
 
 ## Add the connector in Claude
 
@@ -36,14 +41,12 @@ identical in each.
 
 <Stepper>
 
-1. **Open connector settings.**
-   - **Claude Desktop:** open **Settings** → **Connectors**.
-   - **Claude.ai:** open **Settings** → **Connectors** in the web app.
+1. **Open connector settings.** In Claude Desktop or Claude.ai, open **Customize
+   → Connectors**.
 
 2. **Add a custom connector.**
 
-   Scroll to the bottom of the Connectors list and click **Add custom
-   connector**.
+   Click **+**, then **Add custom connector**.
 
 3. **Enter the gateway URL.**
 
@@ -75,7 +78,7 @@ identical in each.
 :::tip
 
 You can adjust which tools Claude is allowed to use per connector. Open the
-connector in Settings → Connectors and toggle individual tools on or off.
+connector in Customize → Connectors and toggle individual tools on or off.
 
 :::
 
@@ -101,21 +104,22 @@ in addition to DCR.
 If you need to script the install or share the configuration with a team, Claude
 Desktop also reads `claude_desktop_config.json`. This approach uses
 [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as a stdio bridge to
-the remote gateway. Use it if your version of Claude Desktop doesn't yet support
-custom remote connectors natively, or if you want the connector to start
-automatically on every launch without going through the UI.
+the gateway. Use it for a gateway running on your computer or when you need
+file-based configuration. This approach requires Node.js and `npx`.
 
 1. In Claude Desktop, open **Settings** → **Developer** → **Edit Config**. This
    opens `claude_desktop_config.json` in your editor.
 2. Add or merge in the following entry, replacing `Zuplo MCP` with the name you
-   want to show, and the URL with your route URL:
+   want to show, and the URL with your route URL. For local development, use
+   `http://127.0.0.1:9000/{routePath}` instead of the HTTPS URL and append
+   `"--allow-http"` to the `args` array:
 
    ```json title="claude_desktop_config.json"
    {
      "mcpServers": {
        "Zuplo MCP": {
          "command": "npx",
-         "args": ["mcp-remote", "https://{deploymentUrl}/{routePath}"]
+         "args": ["-y", "mcp-remote", "https://{deploymentUrl}/{routePath}"]
        }
      }
    }
@@ -130,10 +134,9 @@ automatically on every launch without going through the UI.
 
 :::note
 
-The native custom-connector flow above is the recommended path because it
-supports all of Claude Desktop's MCP features out of the box and does not
-require Node.js. Use the `mcp-remote` bridge only when you specifically need the
-file-based configuration.
+Use native custom connectors for a deployed gateway. They do not require
+Node.js. Use the `mcp-remote` bridge for a local gateway or file-based
+configuration.
 
 :::
 
@@ -147,7 +150,7 @@ file-based configuration.
   configured correctly and that browser cookies are enabled for the gateway
   origin.
 - **Tools do not appear after a successful authorization.** Open the connector
-  in Settings → Connectors and check that each tool is enabled. Disabled tools
+  in Customize → Connectors and check that each tool is enabled. Disabled tools
   are hidden from the attachment menu.
 
 ## Related

package/docs/mcp-gateway/connect-clients/cursor.mdx

@@ -17,7 +17,8 @@ or by using a deeplink that opens Cursor and adds the entry.
 ## Prerequisites
 
 - A Zuplo project with the MCP Gateway plugin configured and at least one MCP
-  route. See the [quickstart](../quickstart.mdx) if you haven't set one up yet.
+  route. See the [quickstart](../../getting-started/mcp-gateway/portal.mdx) if
+  you haven't set one up yet.
 - Cursor installed and signed in.
 
 ## Get the route URL

package/docs/mcp-gateway/connect-clients/overview.mdx

@@ -119,7 +119,8 @@ tracks **what each client can consume**, not what the gateway forwards.
 
 ## Per-client guides
 
-- [Claude Desktop](./claude-desktop.mdx) — add via `claude_desktop_config.json`.
+- [Claude Desktop and Claude.ai](./claude-desktop.mdx) — add a custom remote
+  connector. For a local gateway, use the Claude Desktop manual configuration.
 - [Claude Code](./claude-code.mdx) — add via the `claude mcp add` CLI command.
 - [ChatGPT](./chatgpt.mdx) — add via Settings → Connectors (Developer Mode
   required).

package/docs/mcp-gateway/connect-clients/vs-code.mdx

@@ -15,7 +15,8 @@ view.
 ## Prerequisites
 
 - A Zuplo project with the MCP Gateway plugin configured and at least one MCP
-  route. See the [quickstart](../quickstart.mdx) if you haven't set one up yet.
+  route. See the [quickstart](../../getting-started/mcp-gateway/portal.mdx) if
+  you haven't set one up yet.
 - VS Code installed.
 - The GitHub Copilot extension installed and signed in.
 

package/docs/mcp-gateway/how-it-works.mdx

@@ -256,8 +256,8 @@ A few capabilities are intentionally out of scope, at least today:
 
 - [Set up an MCP Gateway](./code-config/overview.mdx) — the how-to that puts
   this conceptual model into practice.
-- [Quickstart](./quickstart.mdx) — add the MCP Gateway plugin to a Zuplo project
-  and front your first upstream.
+- [Quickstart](../getting-started/mcp-gateway/portal.mdx) — add the MCP Gateway
+  plugin to a Zuplo project and front your first upstream.
 - [Authentication overview](./auth/overview.mdx) — the two OAuth layers expanded
   with the full standards table.
 - [Reference](./reference.mdx) — the full URL catalog, default TTLs,

package/docs/mcp-gateway/how-to/connect-upstream-api-key.mdx

@@ -32,8 +32,8 @@ MCP server and add it to any client you like.
 
 ## Run the wizard with a custom upstream
 
-Follow the [Portal quickstart](../quickstart.mdx) to start an **MCP Gateway
-Virtual Server**, with these choices:
+Follow the [Portal quickstart](../../getting-started/mcp-gateway/portal.mdx) to
+start an **MCP Gateway Virtual Server**, with these choices:
 
 1. **Upstream**: select the **Custom** tab instead of a library server. Set a
    **Name**, the **MCP Server URL** (the upstream provides this), and the
@@ -135,7 +135,8 @@ gateway presents the upstream's API key on their behalf.
 
 ## Related
 
-- [MCP Gateway quickstart](../quickstart.mdx): the full wizard walkthrough.
+- [MCP Gateway quickstart](../../getting-started/mcp-gateway/portal.mdx): the
+  full wizard walkthrough.
 - [Connect an upstream OAuth provider](./connect-upstream-oauth.mdx): the OAuth
   equivalent of this guide.
 - [`set-headers-inbound` policy](../../policies/set-headers-inbound.mdx): the

package/docs/mcp-gateway/how-to/curate-tools.mdx

@@ -30,7 +30,7 @@ the same policy directly in your project files.
 
 The **Tools** step appears while you add or edit an MCP Gateway Virtual Server.
 For a full walkthrough of creating one, see the
-[Portal quickstart](../quickstart.mdx).
+[Portal quickstart](../../getting-started/mcp-gateway/portal.mdx).
 
 1. **Open the Virtual Server wizard.** On the **Code** tab, click **Add Route**
    and choose **MCP Gateway Virtual Server**, then work through the wizard to
@@ -119,6 +119,7 @@ is selected.
   directly, with description and annotation overrides.
 - [Capability filtering](../capability-filtering.mdx): the conceptual model
   behind curation.
-- [Portal quickstart](../quickstart.mdx): create a Virtual Server end to end.
+- [Portal quickstart](../../getting-started/mcp-gateway/portal.mdx): create a
+  Virtual Server end to end.
 - [Connect a gateway to an upstream OAuth provider](./connect-upstream-oauth.mdx):
   pair curation with per-user upstream OAuth.

package/docs/mcp-gateway/overview.mdx

@@ -133,9 +133,9 @@ MCP client discovers and authenticates against it without custom configuration.
 
 ## Next steps
 
-- [Try the quickstart](./quickstart.mdx) — add the MCP Gateway plugin to a Zuplo
-  project, configure Auth0, expose one upstream MCP server, and connect Claude
-  Desktop.
+- [Try the quickstart](../getting-started/mcp-gateway/portal.mdx) — add the MCP
+  Gateway plugin to a Zuplo project, configure Auth0, expose one upstream MCP
+  server, and connect Claude Desktop.
 - [Browse the how-to guides](./connect-clients/overview.mdx) — connect specific
   MCP clients, add more upstreams, curate tools, configure upstream OAuth.
 - [Read how it works](./how-it-works.mdx) — the request lifecycle, the two OAuth