# MCP Gateway quickstart

This guide walks through creating an MCP Gateway project, adding an upstream
(Origin) MCP server, exposing a Virtual MCP with a public URL, picking which
tools to expose, and connecting Claude Desktop. It takes about ten minutes end
to end.

The guide uses the Zuplo Portal. For full code-config control — capability
projection, manual OAuth client registration, custom upstream headers, and so on
— see [How it works](./how-it-works.mdx) and the policy reference pages.

<Stepper>

1. **Create an MCP Gateway project**

   Sign in to the Zuplo Portal and open the
   [new project page](https://portal.zuplo.com/+/account/projects/new). Choose
   the **AI or MCP Gateway** category, then pick the **MCP Gateway** tile. Enter
   a project name and click **Create Project**.

   The new project opens directly on the **Catalog** tab, which lists every
   Virtual MCP the project exposes. It's empty for now.

   :::note

   If the MCP Gateway tile isn't visible, the feature isn't enabled on your
   account yet. [Contact support](mailto:support@zuplo.com) and ask to have MCP
   Gateway turned on.

   :::

   {/* TODO: add screenshot of project type picker */}

1. **Add an Origin MCP**

   An **Origin MCP** is an upstream MCP server the gateway proxies to. Open the
   **Origin MCP** tab and click **Add Origin MCP**.

   Fill in:
   - **Name** — a label for this origin, for example `Linear`.
   - **Description** — optional human-readable summary.
   - **URL** — the upstream MCP server's URL, for example
     `https://mcp.linear.app/mcp`. Replace this with the URL of the MCP server
     you want to front. Any Streamable HTTP MCP server works.

   Click **Create**. The origin appears as a card with the number of tools it
   advertises.

   :::tip

   If you don't have an MCP server in mind to test with, most third-party SaaS
   providers that ship an MCP server document a public URL in their developer
   docs. Search the
   [official MCP server list](https://modelcontextprotocol.io/clients) for
   ideas.

   :::

1. **Create a Virtual MCP**

   A **Virtual MCP** is the endpoint AI clients connect to. Each Virtual MCP
   points at exactly one Origin MCP and exposes a curated subset of that
   Origin's tools. To expose two upstreams, publish two Virtual MCPs.

   Open the **Virtual MCP** tab and click **Add Virtual MCP**. Fill in:
   - **Name** — a label, for example `Linear (prod)`.
   - **Description** — optional.
   - **Slug** — auto-populated from the name. The slug becomes part of the
     public URL: `https://<your-gateway>/v1/mcp/<slug>`. It must use lowercase
     letters and hyphens only.

   Click **Save**. The card shows the public URL and a **Select tools** action.

   {/* TODO: add screenshot of Virtual MCP card */}

1. **Pick tools**

   Click **Select tools** on the Virtual MCP card. The dialog opens with two
   panels:
   - **Origin MCPs** on the left lists every tool advertised by your origins.
     Use the per-origin **Enable all** button to flip them on in bulk, or toggle
     individual tools.
   - **Virtual MCP** on the right shows the tools currently exposed through this
     Virtual MCP. Click **Remove** on a tool to take it out.

   When the right panel reflects the tool set you want, click **Save**.

   Tools you exclude here are filtered out of the Virtual MCP's `tools/list`
   response and direct calls to them return a JSON-RPC `MethodNotFound` error.
   The upstream server never sees those requests.

1. **Connect Claude Desktop**

   Open the **Catalog** tab. Each card represents one Virtual MCP. Click
   **Configuring the MCP** on the card you just created.

   The dialog has tabs for **Claude**, **ChatGPT**, **Cursor**, and **VS Code**.
   Choose **Claude**. Follow the numbered steps in the dialog — they walk
   through opening
   `~/Library/Application Support/Claude/claude_desktop_config.json` (or the
   Windows equivalent) and pasting the snippet shown in the embedded editor,
   which already contains your Virtual MCP's URL.

   Restart Claude Desktop. Open the **Search and tools** panel inside any chat.
   The new MCP server appears in the list.

   :::note

   The first time Claude Desktop calls a tool through the gateway, it triggers
   an OAuth flow. A browser tab opens to your identity provider's login page;
   once authenticated, the gateway lists every upstream you need to connect to
   and walks you through each provider's OAuth one time. Subsequent calls reuse
   the stored credentials.

   :::

1. **Test it**

   In Claude Desktop, prompt the model with something that requires the
   upstream's tools — for the Linear example, "list my open issues" is a good
   test. Claude asks for permission to call the tool, then returns results from
   the upstream MCP server.

   Open the project's **Analytics** tab and switch to the **MCP** tab to see the
   call appear in the events timeline, the success rate, the top capabilities
   table, and the user breakdown.

</Stepper>

## 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 OAuth
  surfaces.
- [Capability filtering](./capability-filtering.mdx) — fine-grained tool
  curation, including renaming descriptions and overriding annotations.
- [Teams and access control](./teams.mdx) — restrict each Virtual MCP to
  specific teams.