zuplo 7.8.7 → 7.8.8

package/docs/{articles/mcp-quickstart.mdx → getting-started/mcp-server/portal.mdx}

@@ -1,20 +1,40 @@
 ---
-title: Dynamic MCP Server - Quickstart
-sidebar_label: "Dynamic MCP Server - Quickstart"
+category: MCP Server
+showLastModified: false
+suggestEdit: false
+title: Getting Started with MCP Server - Portal
+description:
+  Turn an OpenAPI-described API into a managed MCP server in the Zuplo Portal,
+  then connect an MCP client and call your first tool.
 ---
 
+<WizardSteps build="mcp-server" method="portal" />
+
+<MethodTabs build="mcp-server" method="portal" />
+
+Turn an OpenAPI-described API into a managed MCP server. This path builds it in
+the Zuplo Portal.
+
 Zuplo allows you to instantly add a managed MCP Server to your existing API,
 powered by OpenAPI.
 
 If you're not familiar with Zuplo, it's recommended to go through the
-[Step 1](./step-1-setup-basic-gateway.mdx) first.
+[Step 1](../gateway/setup-a-basic-gateway/index.mdx) first.
 
 <Stepper>
 
 1. Create a **new project**
 
-   Sign in to the Zuplo Portal and
-   [create a new project](https://portal.zuplo.com/+/account/projects/new).
+   In the Zuplo Portal, open
+   [**Projects**](https://portal.zuplo.com/+/account/projects), click **New
+   Project**, select **API & MCP Gateway**, enter a project name, and click
+   **Create Project**.
+
+   <ModalScreenshot>
+
+   ![New Zuplo project dialog with API & MCP Gateway selected](/media/mcp-gateway-portal-quickstart/new-project.png)
+
+   </ModalScreenshot>
 
 1. **Import** an **OpenAPI** document
 
@@ -23,7 +43,7 @@ If you're not familiar with Zuplo, it's recommended to go through the
 
    <ModalScreenshot size="sm">
 
-   ![Import OpenAPI](../../public/media/mcp-quickstart/import-openapi.png)
+   ![Import OpenAPI](../../../public/media/mcp-quickstart/import-openapi.png)
 
    </ModalScreenshot>
 
@@ -32,7 +52,7 @@ If you're not familiar with Zuplo, it's recommended to go through the
 
    <ModalScreenshot size="sm">
 
-   ![Complete Import](../../public/media/mcp-quickstart/complete-import.png)
+   ![Complete Import](../../../public/media/mcp-quickstart/complete-import.png)
 
    </ModalScreenshot>
 
@@ -56,7 +76,7 @@ If you're not familiar with Zuplo, it's recommended to go through the
    On your `routes.oas.json` file, choose **Add** and then **Dynamic OpenAPI to
    MCP Server** (3)
 
-   ![Add Route](../../public/media/mcp-quickstart/add-mcp-route.png)
+   ![Add Route](../../../public/media/mcp-quickstart/add-mcp-route.png)
 
    A new route will appear. Confirm the following values:
    - **Summary**: enter `MCP Server`
@@ -65,12 +85,12 @@ If you're not familiar with Zuplo, it's recommended to go through the
 
    Click the **Select Tools** option for your new MCP Server endpoint (1).
 
-   ![Select Tools](../../public/media/mcp-quickstart/select-mcp-tools.png)
+   ![Select Tools](../../../public/media/mcp-quickstart/select-mcp-tools.png)
 
    You should see the MCP tools dialog. Check the tools from your `*.oas.json`
    files, that you want to surface in your MCP Server.
 
-   ![MCP Server](../../public/media/mcp-quickstart/mcp-tools-dialog.png)
+   ![MCP Server](../../../public/media/mcp-quickstart/mcp-tools-dialog.png)
 
    Click **Update Tools** (1)
 
@@ -86,7 +106,7 @@ If you're not familiar with Zuplo, it's recommended to go through the
    [platform.openai.com/playground](https://platform.openai.com/playground)
    (you'll need an OpenAI account).
 
-   ![Add tool](../../public/media/mcp-quickstart/openai-add-tool.png)
+   ![Add tool](../../../public/media/mcp-quickstart/openai-add-tool.png)
 
    Click `Create...` next to the **Tools** label and choose **MCP Server**.
 
@@ -96,13 +116,13 @@ If you're not familiar with Zuplo, it's recommended to go through the
    Zuplo, clicking on your MCP Server route and then clicking **Test**. At the
    top you'll see a button to copy the URL to your clipboard.
 
-   ![Copy MCP Server URL](../../public/media/mcp-quickstart/copy-mcp-server-url.png)
+   ![Copy MCP Server URL](../../../public/media/mcp-quickstart/copy-mcp-server-url.png)
 
    Back to the OpenAI playground...
 
    <ModalScreenshot size="sm">
 
-   ![Connect MCP Server](../../public/media/mcp-quickstart/connect-mcp-server.png)
+   ![Connect MCP Server](../../../public/media/mcp-quickstart/connect-mcp-server.png)
 
    </ModalScreenshot>
 
@@ -115,7 +135,7 @@ If you're not familiar with Zuplo, it's recommended to go through the
 
    <ModalScreenshot size="sm">
 
-   ![Add tools](../../public/media/mcp-quickstart/add-tools.png)
+   ![Add tools](../../../public/media/mcp-quickstart/add-tools.png)
 
    </ModalScreenshot>
 
@@ -132,7 +152,7 @@ If you're not familiar with Zuplo, it's recommended to go through the
 
    Click **Approve** and you should see the todos listed 👏
 
-   ![The prompt](../../public/media/mcp-quickstart/the-prompt.png)
+   ![The prompt](../../../public/media/mcp-quickstart/the-prompt.png)
 
 </Stepper>
 

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 and put Zuplo in front of what you have with Zuplo,
+  in the Portal, locally with the CLI, 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),

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