zuplo 7.8.6 → 7.8.8

package/docs/{mcp-gateway/quickstart-local.mdx → getting-started/mcp-gateway/local.mdx}

@@ -1,13 +1,16 @@
 ---
-title: "MCP Gateway quickstart (Local Dev)"
-sidebar_label: "Quickstart (Local Dev)"
+category: MCP Gateway
+showLastModified: false
+suggestEdit: false
+title: Getting Started with MCP Gateway - Editor
 description:
-  Build an MCP Gateway locally with the Zuplo CLI. Register the plugin, add one
-  upstream MCP server, run it with the loopback dev-login shortcut, and connect
-  Claude Desktop. No identity provider setup required to start.
+  A step-by-step guide to building a mcp gateway with Zuplo using local
+  development.
 ---
 
-<QuickstartPicker mode="local" alternateLink="/mcp-gateway/quickstart" />
+<WizardSteps build="mcp-gateway" method="local" />
+
+<MethodTabs build="mcp-gateway" method="local" />
 
 Build a Zuplo MCP Gateway fronting Linear, running locally at
 `http://127.0.0.1:9000/mcp/linear-v1`. By the end, Claude Desktop connects over
@@ -20,24 +23,23 @@ and a route. This guide uses Linear as the upstream and the built-in
 it out. For production, swap in your provider: the gateway wraps Auth0, Okta,
 Microsoft Entra, Google, Clerk, Cognito, Keycloak, Logto, OneLogin, PingOne, and
 WorkOS, plus a generic OIDC fallback. See the
-[provider catalog](./auth/overview.mdx#identity-providers).
+[provider catalog](../../mcp-gateway/auth/overview.mdx#identity-providers).
 
-Prefer the browser with no local setup? The
-[Portal quickstart](./quickstart.mdx) reaches the same result through the Zuplo
-Portal UI.
+Prefer the browser with no local setup? The [Portal quickstart](./portal.mdx)
+reaches the same result through the Zuplo Portal UI.
 
 ## Prerequisites
 
 - [Node.js](https://nodejs.org/en/download) 24 or higher.
-- A local Zuplo project. Create an empty one with:
+- A local Zuplo project. Create one with:
 
   ```bash
-  npx create-zuplo-api@latest --empty
+  npx create-zuplo-api@latest my-api-project
   ```
 
   Then `cd` into the new directory. See
-  [`create-zuplo-api`](../cli/create-zuplo-api.mdx) for other options, or
-  [import an existing portal project](../articles/local-development.mdx#import-your-existing-project)
+  [`create-zuplo-api`](../../cli/create-zuplo-api.mdx) for other options, or
+  [import an existing portal project](../../articles/local-development.mdx#import-your-existing-project)
   by connecting it to Git and cloning it.
 
 :::note
@@ -45,10 +47,12 @@ Portal UI.
 New projects created with `create-zuplo-api` ship a recent `compatibilityDate`,
 so MCP Gateway features work out of the box. If you're adding the gateway to an
 older project and the build complains about the compatibility date, see
-[Compatibility dates](./code-config/compatibility-dates.mdx).
+[Compatibility dates](../../mcp-gateway/code-config/compatibility-dates.mdx).
 
 :::
 
+## Run your MCP Gateway locally
+
 <Stepper>
 
 1. **Register the MCP Gateway plugin**
@@ -105,7 +109,7 @@ older project and the build complains about the compatibility date, see
    Before deploying, configure an OIDC identity provider. The dev-login endpoint
    only accepts requests from loopback origins and returns `403 Forbidden` for
    other origins. See
-   [Configure local and deployed environments](./code-config/local-development.mdx#configure-local-and-deployed-environments)
+   [Configure local and deployed environments](../../mcp-gateway/code-config/local-development.mdx#configure-local-and-deployed-environments)
    to use one policy with different environment variables for each environment.
 
    :::
@@ -212,7 +216,7 @@ older project and the build complains about the compatibility date, see
    Use `127.0.0.1` in your MCP client URL to match the policy in this tutorial.
    You can use `localhost` instead, but update both URLs to avoid a callback
    mismatch. See
-   [Local development](./code-config/local-development.mdx#use-one-loopback-origin-everywhere).
+   [Local development](../../mcp-gateway/code-config/local-development.mdx#use-one-loopback-origin-everywhere).
 
    :::
 
@@ -237,7 +241,7 @@ older project and the build complains about the compatibility date, see
    :::
 
    For per-client setup details, see
-   [Connect MCP clients](./connect-clients/overview.mdx).
+   [Connect MCP clients](../../mcp-gateway/connect-clients/overview.mdx).
 
 7. **Test it**
 
@@ -258,22 +262,22 @@ scales out to as many upstream MCP servers as you want to front.
 The local gateway on `127.0.0.1` is for development only, and the dev-login
 shortcut works over loopback alone. Before giving others access, swap in a real
 identity provider and ship the gateway through the Zuplo Portal. See
-[environments](../articles/environments.mdx) for setting up a production
+[environments](../../articles/environments.mdx) for setting up a production
 deployment.
 
 :::
 
 ## Next steps
 
-- [Deploy from the Portal](./quickstart.mdx): swap the dev-login shortcut for a
-  real identity provider and ship the gateway through the Zuplo Portal.
-- [Local development](./code-config/local-development.mdx): the dev-login
-  shortcut in depth, environment variables, and local-only quirks.
-- [Connect more clients](./connect-clients/overview.mdx): Claude Code, Cursor,
-  VS Code, ChatGPT, and any other MCP client.
-- [How it works](./how-it-works.mdx): the request lifecycle and the two OAuth
-  surfaces.
-- [Add more upstreams](./code-config/multi-upstream.mdx): front several upstream
-  MCP servers from one Zuplo project.
-- [Capability filtering](./capability-filtering.mdx): curate the tools, prompts,
-  and resources each route exposes.
+- [Deploy from the Portal](./portal.mdx): swap the dev-login shortcut for a real
+  identity provider and ship the gateway through the Zuplo Portal.
+- [Local development](../../mcp-gateway/code-config/local-development.mdx): the
+  dev-login shortcut in depth, environment variables, and local-only quirks.
+- [Connect more clients](../../mcp-gateway/connect-clients/overview.mdx): Claude
+  Code, Cursor, VS Code, ChatGPT, and any other MCP client.
+- [How it works](../../mcp-gateway/how-it-works.mdx): the request lifecycle and
+  the two OAuth surfaces.
+- [Add more upstreams](../../mcp-gateway/code-config/multi-upstream.mdx): front
+  several upstream MCP servers from one Zuplo project.
+- [Capability filtering](../../mcp-gateway/capability-filtering.mdx): curate the
+  tools, prompts, and resources each route exposes.

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

@@ -1,13 +1,15 @@
 ---
-title: "MCP Gateway quickstart (Portal)"
-sidebar_label: "Quickstart"
+category: MCP Gateway
+showLastModified: false
+suggestEdit: false
+title: Getting Started with MCP Gateway - Portal
 description:
-  Build an MCP Gateway in the Zuplo Portal. Create a project, add an MCP Gateway
-  Virtual Server with the guided wizard, set your identity provider's
-  environment variables, and connect Claude Desktop. No local setup required.
+  A step-by-step guide to building a mcp gateway with Zuplo using Zuplo Portal.
 ---
 
-<QuickstartPicker mode="portal" alternateLink="/mcp-gateway/quickstart-local" />
+<WizardSteps build="mcp-gateway" method="portal" />
+
+<MethodTabs build="mcp-gateway" method="portal" />
 
 Build a Zuplo MCP Gateway fronting Linear at
 `https://<your-gateway>/mcp/linear-v1`, entirely in the browser. By the end,
@@ -21,40 +23,53 @@ authenticate upstream. This guide uses Linear and Auth0, but the wizard supports
 any upstream in its library (plus custom servers) and every identity provider
 Zuplo wraps.
 
-Prefer the CLI? The [local quickstart](./quickstart-local.mdx) reaches the same
-result on your machine.
+Prefer the CLI? The [local quickstart](./local.mdx) reaches the same result on
+your machine.
 
 ## Prerequisites
 
 - A free [Zuplo account](https://portal.zuplo.com).
 - An account with your identity provider. For the Auth0 example, that's an Auth0
   tenant with a Regular Web Application configured. The
-  [Configuring Auth0](./auth/configuring-auth0.mdx#set-up-the-auth0-tenant)
+  [Configuring Auth0](../../mcp-gateway/auth/configuring-auth0.mdx#set-up-the-auth0-tenant)
   guide covers the dashboard side. From it you'll need the **domain**, **client
   ID**, and **client secret**.
 
+## Create and test your MCP Gateway
+
 <Stepper>
 
-1. **Create a project and start a Virtual Server**
+1. **Create a Zuplo project**
+
+   In the Zuplo Portal, open
+   [**Projects**](https://portal.zuplo.com/+/account/projects), click **New
+   Project**, and select **API & MCP Gateway**. Name the project
+   `my-mcp-gateway`, choose a blank project rather than importing one, and click
+   **Create Project**. The project opens on the **Project** tab.
+
+   <ModalScreenshot>
+
+   ![New Zuplo project dialog with API & MCP Gateway selected](/media/mcp-gateway-portal-quickstart/new-project.png)
+
+   </ModalScreenshot>
+
+2. **Start an MCP Gateway Virtual Server**
 
-   Sign in to the Zuplo Portal and
-   [create a new empty project](https://portal.zuplo.com/+/account/projects/new)
-   (choose a blank project rather than importing one). The project opens on the
-   **Project** tab; click the **Code** tab.
+   Open the **Code** tab in the project you created.
 
-   Click **Add Route**, then choose **MCP Gateway Virtual Server** from the
-   menu.
+   Click **Add to Gateway** (or **Add Route** if the project already has
+   routes), then choose **MCP Gateway Virtual Server** from the menu.
 
    <ModalScreenshot size="md">
 
-   ![Add an MCP Gateway Virtual Server from the Add Route menu](../../public/media/mcp-gateway-quickstart/01-add-route.png)
+   ![Add an MCP Gateway Virtual Server from the Add Route menu](../../../public/media/mcp-gateway-quickstart/01-add-route.png)
 
    </ModalScreenshot>
 
    The **New MCP Gateway Virtual Server** wizard opens and walks through four
    steps: the upstream server, inbound auth, tools, and outbound auth.
 
-2. **Choose the upstream MCP server**
+3. **Choose the upstream MCP server**
 
    On the **Upstream** step, pick the MCP server this virtual server fronts.
    Select **Linear** from the **Library** of pre-configured servers. The
@@ -65,7 +80,7 @@ result on your machine.
 
    <ModalScreenshot size="md">
 
-   ![Select Linear from the upstream server library](../../public/media/mcp-gateway-quickstart/02-upstream.png)
+   ![Select Linear from the upstream server library](../../../public/media/mcp-gateway-quickstart/02-upstream.png)
 
    </ModalScreenshot>
 
@@ -76,7 +91,7 @@ result on your machine.
 
    :::
 
-3. **Choose an identity provider**
+4. **Choose an identity provider**
 
    The **Inbound Auth** step controls how MCP clients authenticate _to_ the
    gateway. Pick your identity provider; this guide uses **Auth0**. The wizard
@@ -84,7 +99,7 @@ result on your machine.
 
    <ModalScreenshot size="md">
 
-   ![Choose Auth0 as the identity provider](../../public/media/mcp-gateway-quickstart/03-inbound-auth.png)
+   ![Choose Auth0 as the identity provider](../../../public/media/mcp-gateway-quickstart/03-inbound-auth.png)
 
    </ModalScreenshot>
 
@@ -93,11 +108,12 @@ result on your machine.
    The catalog includes WorkOS, Google, Okta, Microsoft Entra, Cognito, Clerk,
    Keycloak, Logto, OneLogin, and PingOne. You can also select an existing
    inbound policy, or pick **None** if this route doesn't need gateway OAuth.
-   See the [provider catalog](./auth/overview.mdx#identity-providers).
+   See the
+   [provider catalog](../../mcp-gateway/auth/overview.mdx#identity-providers).
 
    :::
 
-4. **Decide what the virtual server exposes**
+5. **Decide what the virtual server exposes**
 
    The **Tools** step controls which tools, prompts, and resources the virtual
    server exposes to its clients:
@@ -111,7 +127,7 @@ result on your machine.
 
    <ModalScreenshot size="md">
 
-   ![Choose Filter & curate or Passthrough for the exposed catalog](../../public/media/mcp-gateway-quickstart/04-tools.png)
+   ![Choose Filter & curate or Passthrough for the exposed catalog](../../../public/media/mcp-gateway-quickstart/04-tools.png)
 
    </ModalScreenshot>
 
@@ -122,7 +138,7 @@ result on your machine.
 
    :::
 
-5. **Configure upstream authentication**
+6. **Configure upstream authentication**
 
    On **Outbound Auth**, leave **User OAuth** selected so each user connects
    their own Linear account. Click **Next**.
@@ -133,7 +149,7 @@ result on your machine.
 
    <ModalScreenshot size="md">
 
-   ![Choose User OAuth and Dynamic client registration](../../public/media/mcp-gateway-quickstart/05-outbound-auth.png)
+   ![Choose User OAuth and Dynamic client registration](../../../public/media/mcp-gateway-quickstart/05-outbound-auth.png)
 
    </ModalScreenshot>
 
@@ -148,7 +164,7 @@ result on your machine.
    The wizard adds the new MCP route to `config/routes.oas.json` and scaffolds
    the inbound auth and token-exchange policies. **Save** the project.
 
-6. **Set your identity provider's environment variables**
+7. **Set your identity provider's environment variables**
 
    In `config/policies.json`, set the Auth0 policy's environment variable
    references to match these names, then save the file:
@@ -195,7 +211,7 @@ result on your machine.
 
    :::
 
-7. **Verify the OAuth policy is wired up**
+8. **Verify the OAuth policy is wired up**
 
    Click the **Test** button next to the route's path and send a `POST` with no
    `Authorization` header. You should get a `401 Unauthorized` whose
@@ -219,7 +235,7 @@ result on your machine.
 
    :::
 
-8. **Connect Claude Desktop**
+9. **Connect Claude Desktop**
 
    Your route is live at `https://<your-gateway>/mcp/linear-v1`. Find the public
    URL via the **Gateway deployed** button in the toolbar.
@@ -242,19 +258,19 @@ result on your machine.
    :::
 
    For per-client setup details, see
-   [Connect MCP clients](./connect-clients/overview.mdx).
+   [Connect MCP clients](../../mcp-gateway/connect-clients/overview.mdx).
 
-9. **Test it**
+10. **Test it**
 
-   In Claude Desktop, prompt the model with something that requires Linear.
-   "list my open issues" works well. Claude asks for permission to call the
-   tool, then returns results proxied through the gateway.
+    In Claude Desktop, prompt the model with something that requires Linear.
+    "list my open issues" works well. Claude asks for permission to call the
+    tool, then returns results proxied through the gateway.
 
-   Open the project's
-   [**Observability → Analytics**](https://portal.zuplo.com/+/account/project/analytics)
-   view and select the **MCP** section to see the call appear in the events
-   timeline, the success rate, the top capabilities table, and the user
-   breakdown.
+    Open the project's
+    [**Observability → Analytics**](https://portal.zuplo.com/+/account/project/analytics)
+    view and select the **MCP** section to see the call appear in the events
+    timeline, the success rate, the top capabilities table, and the user
+    breakdown.
 
 </Stepper>
 
@@ -267,7 +283,7 @@ again for each additional upstream you want to front.
 
 The Working Copy (Development) URLs are fine for testing everything above. Once
 you've confirmed the virtual server works, set up a production deployment via
-[environments](../articles/environments.mdx) before giving others access. The
+[environments](../../articles/environments.mdx) before giving others access. The
 development URL is tied to your working copy and isn't meant for shared or
 production traffic.
 
@@ -275,12 +291,12 @@ production traffic.
 
 ## Next steps
 
-- [Connect more clients](./connect-clients/overview.mdx): Claude Code, Cursor,
-  VS Code, ChatGPT, and any other MCP client.
-- [How it works](./how-it-works.mdx): the request lifecycle and the two OAuth
-  surfaces.
-- [Capability filtering](./capability-filtering.mdx): go deeper on the Curate
-  option, overriding tool descriptions and annotations, not just
+- [Connect more clients](../../mcp-gateway/connect-clients/overview.mdx): Claude
+  Code, Cursor, VS Code, ChatGPT, and any other MCP client.
+- [How it works](../../mcp-gateway/how-it-works.mdx): the request lifecycle and
+  the two OAuth surfaces.
+- [Capability filtering](../../mcp-gateway/capability-filtering.mdx): go deeper
+  on the Curate option, overriding tool descriptions and annotations, not just
   include/exclude.
-- [Add more upstreams](./code-config/multi-upstream.mdx): front several upstream
-  MCP servers from one Zuplo project.
+- [Add more upstreams](../../mcp-gateway/code-config/multi-upstream.mdx): front
+  several upstream MCP servers from one Zuplo project.

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

@@ -0,0 +1,152 @@
+---
+category: MCP Server
+showLastModified: false
+suggestEdit: false
+sidebar_label: Agent
+title: Getting Started with MCP Server - Agent
+description:
+  Use a coding agent to expose a Todo API as an MCP server, review its single
+  read-only tool, and verify it with MCP Inspector.
+---
+
+<WizardSteps build="mcp-server" method="agent" />
+
+<MethodTabs build="mcp-server" method="agent" />
+
+Use a coding agent to turn a Todo API into an MCP server. The finished server
+exposes one read-only tool, which you'll call from MCP Inspector before using it
+with your agent.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/en/download) 24 or later.
+- An installed coding agent, such as Codex, Claude Code, or Cursor.
+- A [Zuplo account](https://portal.zuplo.com).
+
+## Build your MCP server with an agent
+
+<Stepper>
+
+1. **Create the project**
+
+   Run:
+
+   ```bash
+   npx create-zuplo-api@latest todo-mcp
+   cd todo-mcp
+   ```
+
+   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. **Ask the agent to expose one tool**
+
+   Open your agent in the project directory and use this prompt:
+
+   ```text
+   Read the project instructions and bundled Zuplo docs. Turn the default Todo
+   API into an MCP server with exactly one read-only tool.
+
+   In config/routes.oas.json, keep the existing GET /todos URL forward handler
+   pointing to https://todo.zuplo.io. Set its operationId to getTodos. Add an
+   x-zuplo-route.mcp object with type "tool", name "getTodos", and annotations
+   { "readOnlyHint": true }.
+
+   Add a POST-only /mcp operation with operationId todo-mcp-server, a 200
+   response description, and x-zuplo-route with corsPolicy "none" and handler:
+   {
+     "module": "$import(@zuplo/runtime)",
+     "export": "mcpServerHandler",
+     "options": {
+       "name": "Todo MCP server",
+       "version": "1.0.0",
+       "operations": [{ "file": "./config/routes.oas.json", "id": "getTodos" }]
+     }
+   }
+
+   Do not expose create, update, or delete operations as MCP tools. Keep the
+   sample unauthenticated for this local exercise; don't claim it is ready
+   for private data. Preserve unrelated files and routes.
+
+   Run npm run dev and confirm GET /todos returns 200. Use an MCP client to
+   check that tools/list exposes exactly getTodos and tools/call returns todos.
+   If you cannot run an MCP client, say which checks remain for me. Do not
+   deploy. Show the diff and explain how to test with MCP Inspector.
+   ```
+
+   For the underlying configuration, see the
+   [MCP Server handler](../../handlers/mcp-server.mdx).
+
+3. **Review the route and start the server**
+
+   Check the diff before running the agent's code. The `/mcp` handler's
+   `operations` list should contain only `getTodos`, and that ID must match
+   `GET /todos`.
+
+   Start `npm run dev` if the agent hasn't left it running. In another terminal,
+   run:
+
+   ```bash
+   curl -i http://localhost:9000/todos
+   ```
+
+   Expect `200 OK` and a JSON response containing todos.
+
+4. **Test the MCP tool**
+
+   Start MCP Inspector in another terminal:
+
+   ```bash
+   npx @modelcontextprotocol/inspector
+   ```
+
+   Open the URL printed by Inspector. Select **Streamable HTTP**, enter
+   `http://localhost:9000/mcp`, and connect. List tools: there should be exactly
+   one, `getTodos`. Run it with an empty arguments object `{}`. The result
+   should contain the Todo API response without a tool error.
+
+   A missing tool usually means the `operationId` and handler's `id` don't
+   match. If the tool errors, test `/todos` directly to distinguish an upstream
+   problem from an MCP configuration problem.
+
+5. **Connect your coding agent**
+
+   For Codex, register the HTTP MCP server from your terminal:
+
+   ```bash
+   codex mcp add todo-api --url http://localhost:9000/mcp
+   ```
+
+   Start a new Codex session so it loads the server. For another client, use its
+   HTTP MCP configuration with the same URL. Keep the gateway running, then ask
+   the agent to `Use getTodos to list the todos`. Approve the tool call and
+   check that the response matches the Inspector result.
+
+   Cloud-hosted clients can't reach your computer's `localhost`. To use one,
+   [deploy the project](../gateway/deploy-to-the-edge/local.mdx) and provide its
+   hosted `/mcp` URL.
+
+</Stepper>
+
+This local sample has no authentication. Before exposing private operations,
+configure
+[MCP server authentication](../../articles/configuring-auth0-for-mcp-auth.mdx).
+
+## Next steps
+
+- [Choose tools in the Route Designer](./local.mdx) to add more operations.
+- [Configure the MCP Server handler](../../handlers/mcp-server.mdx) for your
+  API's tools.
+- [Add authentication](../../articles/configuring-auth0-for-mcp-auth.mdx) before
+  sharing a server that accesses private data.

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

@@ -0,0 +1,25 @@
+---
+category: MCP Server
+fullWidth: true
+disablePager: true
+showLastModified: false
+suggestEdit: false
+centered: false
+toc: false
+title: Getting Started with MCP Server
+description:
+  Turn an OpenAPI-described API into a managed MCP server with Zuplo, in the
+  Portal, locally with the CLI, or with an AI agent.
+---
+
+<WizardSteps build="mcp-server" />
+
+An MCP server makes API operations available as tools for AI assistants through
+the Model Context Protocol (MCP). This tutorial adds an MCP interface to a
+sample Todo API using its OpenAPI document.
+
+Choose a workflow to create the server, select its tools, and test a tool call.
+The sample API is provided. Use an MCP client, such as MCP Inspector, to test
+the result. For the local guides, use a client that can reach your machine.
+
+<MethodPicker build="mcp-server" />

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

@@ -1,14 +1,25 @@
 ---
-title: Dynamic MCP Server - Quickstart
-sidebar_label: "Dynamic MCP Server - Quickstart"
+category: MCP Server
+showLastModified: false
+suggestEdit: false
+title: Getting Started with MCP Server - Editor
+description:
+  A step-by-step guide to building a mcp server with Zuplo using local
+  development.
 ---
 
+<WizardSteps build="mcp-server" method="local" />
+
+<MethodTabs build="mcp-server" method="local" />
+
+Turn an OpenAPI-described API into a managed MCP server. This path builds it
+with the Zuplo CLI and your editor.
+
 Zuplo allows you to instantly add a managed MCP Server to your existing API,
-powered by OpenAPI. In this guide we'll build one locally using the
-[Zuplo CLI](../cli/overview.mdx).
+powered by OpenAPI.
 
 If you're not familiar with Zuplo, it's recommended to go through
-[Step 1](./step-1-setup-basic-gateway-local.mdx) first.
+[Step 1](../gateway/setup-a-basic-gateway/local.mdx) first.
 
 <Stepper>
 
@@ -22,8 +33,8 @@ If you're not familiar with Zuplo, it's recommended to go through
    npm run dev
    ```
 
-   See [Step 1](./step-1-setup-basic-gateway-local.mdx) for a walkthrough of the
-   `create-zuplo-api` prompts.
+   See [Step 1](../gateway/setup-a-basic-gateway/local.mdx) for a walkthrough of
+   the `create-zuplo-api` prompts.
 
 1. Test the **Get all todos** route
 
@@ -42,7 +53,7 @@ If you're not familiar with Zuplo, it's recommended to go through
    On your `routes.oas.json` file, choose **Add** and then **Dynamic OpenAPI to
    MCP Server**.
 
-   ![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`
@@ -51,12 +62,12 @@ If you're not familiar with Zuplo, it's recommended to go through
 
    Click the **Select Tools** option for your new MCP Server endpoint.
 
-   ![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**, then click **Save** at the bottom left.
    Congratulations, you just published your first MCP Server! It's now available
@@ -66,7 +77,7 @@ If you're not familiar with Zuplo, it's recommended to go through
 
    You can connect any MCP client that can reach your local gateway. The AI
    coding agent you configured in
-   [Step 1](./step-1-setup-basic-gateway-local.mdx) (such as Claude Code or
+   [Step 1](../gateway/setup-a-basic-gateway/local.mdx) (such as Claude Code or
    Cursor) is a great option — point it at your local MCP server URL:
 
    ```
@@ -80,8 +91,8 @@ If you're not familiar with Zuplo, it's recommended to go through
    Cloud clients like the
    [OpenAI playground](https://platform.openai.com/playground) can't reach
    `localhost`. To use one, deploy your project first — see
-   [Step 4](./step-4-deploying-to-the-edge-local.mdx) — and use your deployed
-   MCP server URL instead.
+   [Step 4](../gateway/deploy-to-the-edge/local.mdx) — and use your deployed MCP
+   server URL instead.
 
    :::