Copy page

Connect Clients

Connect Cursor

Cursor is an AI-first code editor. It speaks the MCP Streamable HTTP transport natively and supports OAuth-protected remote MCP servers, which is exactly what the Zuplo MCP Gateway exposes.

You can install the gateway connector in Cursor in two ways: via a one-click deeplink that Portal generates for you, or by editing Cursor's mcp.json configuration directly.

Prerequisites

• A Zuplo MCP Gateway project with at least one Virtual MCP server. See the quickstart if you haven't created one yet.
• Cursor installed and signed in.

Option 1: One-click install from Portal

The fastest path is to let Portal generate the install link for you.

The deeplink uses Cursor's cursor:// URL scheme:

Code
cursor://anysphere.cursor-deeplink/mcp/install?name={name}&config={base64-config}

{base64-config} is the JSON object {"url": "https://{deploymentUrl}/v1/mcp/{slug}"} encoded with btoa().

Option 2: Edit mcp.json directly

Cursor reads MCP server configuration from two locations:

• ~/.cursor/mcp.json — applies to every project you open with Cursor.
• .cursor/mcp.json in a project's root — applies only to that project, and can be committed to version control to share with your team.

Add an entry under mcpServers, using a friendly name as the key and the Virtual MCP URL as the value:

~/.cursor/mcp.json
{
  "mcpServers": {
    "Zuplo MCP": {
      "url": "https://{deploymentUrl}/v1/mcp/{slug}"
    }
  }
}

Restart Cursor after editing the file. The first time Cursor connects, it opens a browser to complete the OAuth flow.

Environment variable interpolation

Cursor's mcp.json supports interpolation so you don't need to hardcode sensitive values:

• ${env:NAME} — resolves to the environment variable NAME.
• ${workspaceFolder} — resolves to the project root.
• ${userHome} — resolves to your home directory.

These work inside command, args, env, url, and headers. For example, to use a per-environment deployment URL:

Code
{
  "mcpServers": {
    "Zuplo MCP": {
      "url": "${env:ZUPLO_MCP_URL}"
    }
  }
}

What Cursor supports

Cursor registers itself with the gateway through Dynamic Client Registration and supports:

• Tools — invoke gateway-exposed tools from Composer.
• Prompts — surface gateway prompts in the prompt picker.
• Roots — declare the project root to the server.
• Elicitation — handle form-mode and URL-mode elicitation requests from the gateway, including upstream re-authorization prompts.
• MCP Apps — render interactive HTML widgets from compatible servers.

Troubleshooting

• The Install MCP in Cursor button does not open Cursor. Make sure Cursor is installed and that your browser allows opening the cursor:// URL scheme. As a fallback, copy the URL the browser shows and paste it into your address bar.
• Cursor shows "Failed to connect" for the server. Open ~/.cursor/mcp.json and confirm the URL is correct and reachable. If the gateway is healthy, restart Cursor to retry the OAuth flow.
• Tools do not refresh after upstream changes. Restart Cursor or toggle the server off and back on in the MCP settings. Cursor caches the tool list per server.

Related

• Connect MCP clients overview
• Cursor's docs: Model Context Protocol
• Authentication overview