Copy page

Connect MCP 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.

Add the gateway connector in Cursor by editing Cursor's mcp.json configuration or by using a deeplink that opens Cursor and adds the entry.

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.
• Cursor installed and signed in.

Get the route URL

Each MCP route in config/routes.oas.json is reachable at https://{deploymentUrl}/{routePath} once deployed — for example https://{deploymentUrl}/mcp/linear-v1.

Edit mcp.json

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 route URL as the value:

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

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

• 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