# 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](../quickstart.mdx) 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](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 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. 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 route URL (for example `https://{deploymentUrl}/mcp/linear-v1`). 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 the upstream connection.** The gateway shows a consent page with the upstream MCP server the route proxies to. Click **Connect** next to the upstream and complete its OAuth flow. Once it's 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. :::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). 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`. This approach uses [`mcp-remote`](https://www.npmjs.com/package/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: ```json title="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. :::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)