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

What Claude Desktop supports

Claude Desktop registers itself with the gateway through Dynamic Client Registration (DCR). 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) 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 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:

   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.

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
• Anthropic's official guide: Connect to remote MCP servers
• Anthropic's setup article: Get started with custom connectors using remote MCP
• Authentication overview