Connect MCP clients
The Zuplo MCP Gateway exposes each MCP route 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 MCP route URL
Each MCP route in config/routes.oas.json is reachable at:
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 for the project. The {routePath} is the path you set on
the route in routes.oas.json. A typical convention is /mcp/<provider>-v<n>,
so a Linear route looks like
https://acme-mcp-main-abc123.d2.zuplo.dev/mcp/linear-v1.
For local development with zuplo dev, the URL is
http://127.0.0.1:9000/{routePath} — for example
http://127.0.0.1:9000/mcp/linear-v1. See
Local development.
Transport
The gateway uses the Streamable HTTP transport defined in the MCP
specification. Clients POST JSON-RPC requests to the MCP route 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 route 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, Entra, Google, Cognito, or any of the other supported IdPs — to sign in. After login, the gateway issues an access token bound to the route URL and returns it to the client through the standard OAuth 2.1 Authorization Code with PKCE flow.
- Upstream consent. If the route's upstream MCP server requires per-user OAuth (Linear, Notion, Stripe, GitHub, and so on), the gateway shows a consent page with a Connect button for the upstream. Clicking Connect opens the upstream provider's OAuth flow in the same browser. Once the 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 and Claude.ai — add a custom remote connector. For a local gateway, use the Claude Desktop manual configuration.
- 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.