Connect MCP Clients
The Zuplo MCP Gateway exposes each Virtual MCP server at a stable HTTPS URL that any modern MCP client can connect to. Clients speak the Streamable HTTP transport, complete an OAuth flow on first use, and then call tools, read resources, and run prompts through the gateway just as they would against any other remote MCP server.
This page covers the connection model and links to a step-by-step guide for each of the major clients.
The Virtual MCP URL
Every Virtual MCP server has a public URL of the form:
Code
The {deploymentUrl} is your project's deployment URL — for example
acme-mcp-main-abc123.d2.zuplo.dev for a default Zuplo deployment, or a custom
domain you configure in Portal. The {slug} is the value you set when you
created the Virtual MCP.
If you build your gateway with code configuration instead of Portal, the URL
matches whatever path you set on the route — for example
https://{deploymentUrl}/mcp/linear-v1 when the route in routes.oas.json is
/mcp/linear-v1. See Configuring with code for
details.
Where to find the URL in Portal
- Open the MCP Gateway project.
- Land on the Catalog tab (the project root).
- Each Virtual MCP server appears as a card. Click Configuring the MCP on the card.
- The dialog opens with tabs for Claude, ChatGPT, Cursor, and VS Code. Each tab includes the full URL inside a ready-to-paste configuration snippet.
You can also copy the URL directly from a Virtual MCP card on the Virtual MCP tab — click the Copy URL button next to the server name.
Transport
The gateway uses the Streamable HTTP transport defined in the MCP
specification. Clients POST JSON-RPC requests to the Virtual MCP URL. The
gateway does not currently accept GET requests for server-sent event streams —
it returns 405 Method Not Allowed — so configure your client to use Streamable
HTTP, not the older two-endpoint HTTP+SSE transport.
For more on transports, see the MCP transports specification.
What happens on first connect
The first time a user connects, the gateway runs two distinct OAuth handshakes before any tool call reaches an upstream MCP server.
- Discovery. The client POSTs an MCP request to the Virtual MCP URL without
an
Authorizationheader. The gateway responds with401 Unauthorizedand aWWW-Authenticateheader that points at the gateway's Protected Resource Metadata document (RFC 9728). - Gateway login. The client opens the gateway's authorization endpoint in a browser. The gateway redirects the user to your identity provider (Auth0, Okta, or any OIDC IdP) to sign in. After login, the gateway issues an access token bound to the Virtual MCP URL and returns it to the client through the standard OAuth 2.1 Authorization Code with PKCE flow.
- Upstream consent. If the Virtual MCP routes to an upstream MCP server that requires per-user OAuth (Linear, Notion, Stripe, GitHub, and so on), the gateway shows a consent page listing each upstream and asks the user to click Connect for each one. Each click opens the upstream provider's OAuth flow in the same browser. Once every required upstream is connected, the user clicks Authorize and the gateway returns the access token to the client.
After the first connect, subsequent requests reuse the issued access token and the stored upstream credentials. Tokens refresh automatically. If the gateway needs the user to re-consent to an upstream — for example, when an upstream provider revokes the gateway's credentials — the client receives a JSON-RPC error with a URL to open in the browser to complete re-consent.
For the full authentication model, see Authentication overview.
Client compatibility
The table below summarizes which MCP spec features each major client supports today. All clients listed here support remote Streamable HTTP and work with the Zuplo MCP Gateway.
| Client | Tools | Prompts | Resources | Roots | Sampling | Elicitation | DCR | CIMD | Apps |
|---|---|---|---|---|---|---|---|---|---|
| Claude Desktop | yes | yes | yes | yes | – | – | yes | – | yes |
| Claude.ai (web) | yes | yes | yes | – | – | – | yes | yes | yes |
| Claude Code | yes | yes | yes | yes | – | yes | yes | – | – |
| ChatGPT | yes | – | – | – | – | – | yes | yes | yes |
| Cursor | yes | yes | – | yes | – | yes | yes | – | yes |
| VS Code (GitHub Copilot) | yes | yes | yes | yes | yes | yes | yes | yes | yes |
| Windsurf (Cascade) | yes | – | – | – | – | – | yes | – | – |
| Goose | yes | yes | yes | yes | yes | yes | yes | – | yes |
| Gemini CLI | yes | yes | – | – | – | – | yes | – | – |
| GitHub Copilot CLI | yes | – | – | – | yes | yes | yes | – | – |
| Postman | yes | yes | yes | – | yes | yes | – | – | yes |
| MCPJam | yes | yes | yes | – | – | yes | yes | yes | yes |
| Continue | yes | yes | yes | – | – | – | – | – | yes |
| LibreChat | yes | – | – | – | – | – | yes | – | – |
| JetBrains AI Assistant | yes | – | – | – | – | – | – | – | – |
Capability data is sourced from the official MCP clients page. Clients ship new features frequently; check the client's own documentation for the latest support status.
The gateway exposes whatever capabilities the upstream MCP servers expose. If an
upstream server only ships tools, a client that supports resources won't see
anything in resources/list for that server. The compatibility matrix above
tracks what each client can consume, not what the gateway forwards.
Per-client guides
- Claude Desktop — add via
claude_desktop_config.json. - Claude Code — add via the
claude mcp addCLI command. - ChatGPT — add via Settings → Connectors (Developer Mode required).
- Cursor — add via
.cursor/mcp.jsonor the one-click install link. - VS Code — add via
.vscode/mcp.jsonor thecode --add-mcpCLI command. - Other clients — Windsurf, Goose, Gemini CLI, GitHub Copilot CLI, Postman, MCPJam, Continue, LibreChat, JetBrains AI Assistant.