# Connect Claude Desktop and Claude.ai

Claude Desktop and Claude.ai connect to remote MCP servers through **Custom
Connectors**. Adding a Zuplo Virtual MCP server takes two steps: paste the
gateway URL into Claude's connector settings, then complete the browser-based
OAuth flow.

## Prerequisites

- A Zuplo MCP Gateway project with at least one Virtual MCP server. See the
  [quickstart](../quickstart.mdx) if you haven't created one 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),
  custom connectors are available on Free, Pro, Max, Team, and Enterprise plans.
  Free plans are limited to one custom connector. Team and Enterprise plans
  require an organization owner to add the connector first before individual
  members can authenticate.

## Get the Virtual MCP URL

1. Open the
   [MCP Gateway project Catalog](https://portal.zuplo.com/+/account/project).
2. Find the card for the Virtual MCP server you want to connect.
3. Click **Configuring the MCP** and copy the URL shown in the dialog. The URL
   has the form `https://{deploymentUrl}/v1/mcp/{slug}`.

## Add the connector in Claude

Both Claude Desktop and Claude.ai support custom connectors. The flow is nearly
identical in each.

<Stepper>

1. **Open connector settings.**
   - **Claude Desktop:** open **Settings** → **Connectors**.
   - **Claude.ai:** open **Settings** → **Connectors** in the web app.

2. **Add a custom connector.**

   Scroll to the bottom of the Connectors list and click **Add custom
   connector**.

3. **Enter the gateway URL.**

   Paste the Virtual MCP URL from Portal. Optionally name the connector (the
   name is what Claude shows you in the connector list and in tool results) and
   click **Add**.

4. **Sign in to the gateway.**

   Claude opens the gateway's OAuth flow in a browser. Sign in with the identity
   provider you configured for the gateway (Auth0, Okta, or any OIDC provider).

5. **Complete upstream connections.**

   The gateway shows a consent page listing every upstream MCP server the
   Virtual MCP routes to. Click **Connect** next to each upstream and complete
   its OAuth flow. Once every required upstream is connected, click
   **Authorize** to finish.

6. **Verify the connector is active.**

   Back in Claude, the new connector appears in your Connectors list. Open a
   chat and click the attachment icon to confirm tools, prompts, and resources
   from the gateway are available.

</Stepper>

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

:::

## What Claude Desktop supports

Claude Desktop registers itself with the gateway through
[Dynamic Client Registration (DCR)](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization).
The gateway accepts DCR clients and stores them for the lifetime of the client's
TTL.

Claude Desktop supports the following MCP capabilities from the gateway:

- **Tools** — invoke gateway-exposed tools by name.
- **Prompts** — surface prompts as commands in the chat interface.
- **Resources** — attach resources to messages from the attachment menu.
- **Roots** — declare filesystem boundaries to the server.
- **MCP Apps** — render interactive HTML widgets inline in the conversation.

Claude.ai (the web version) supports the same set, plus
[Client ID Metadata Documents (CIMD)](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)
in addition to DCR.

## Use a manual config file (advanced)

If you need to script the install or share the configuration with a team, Claude
Desktop also reads `claude_desktop_config.json`. The Portal generates a snippet
for this case that uses [`mcp-remote`](https://www.npmjs.com/package/mcp-remote)
as a stdio bridge to the remote gateway. Use this approach 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.

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 Virtual MCP URL:

   ```json title="claude_desktop_config.json"
   {
     "mcpServers": {
       "Zuplo MCP": {
         "command": "npx",
         "args": ["mcp-remote", "https://{deploymentUrl}/v1/mcp/{slug}"]
       }
     }
   }
   ```

3. Save the file and restart Claude Desktop.
4. The first time Claude Desktop starts the bridge, it opens a browser window to
   complete the OAuth flow against the gateway. Sign in and approve the consent
   page as you would for a native connector.
5. Verify the server appears in Claude Desktop. Tools are available behind the
   attachment icon.

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

:::

## Troubleshooting

- **Browser does not open during OAuth.** Verify the gateway's deployment URL is
  reachable from your machine and your firewall or proxy allows outbound HTTPS
  to the gateway origin.
- **Consent page shows "Connect" for every upstream every time.** This means the
  gateway never received the user's signed-in identity. Confirm that your IdP is
  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
  are hidden from the attachment menu.

## Related

- [Connect MCP clients overview](./overview.mdx)
- Anthropic's official guide:
  [Connect to remote MCP servers](https://modelcontextprotocol.io/docs/develop/connect-remote-servers)
- Anthropic's setup article:
  [Get started with custom connectors using remote MCP](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp)
- [Authentication overview](../auth/overview.mdx)