Connect Claude Desktop and Claude.ai

Claude Desktop and Claude.ai connect to remote MCP servers through Custom Connectors. Adding a Zuplo MCP route takes two steps: paste the route URL into 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 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, 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 route URL

Each MCP route in config/routes.oas.json is reachable at https://{deploymentUrl}/{routePath} once deployed (or http://127.0.0.1:9000/{routePath} when running locally with zuplo dev). The {routePath} is the path you set on the route — for example /mcp/linear-v1.

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

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. This approach uses mcp-remote as a stdio bridge to the remote gateway. Use it 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 route URL:

   claude_desktop_config.json
   {
     "mcpServers": {
       "Zuplo MCP": {
         "command": "npx",
         "args": ["mcp-remote", "https://{deploymentUrl}/{routePath}"]
       }
     }
   }

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