# Connect Cursor

[Cursor](https://cursor.com/) 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](../quickstart.mdx) 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.

<Stepper>

1. Open the
   [MCP Gateway project Catalog](https://portal.zuplo.com/+/account/project).

2. Find the card for the Virtual MCP server you want to connect.

3. Click **Configuring the MCP** and switch to the **Cursor** tab.

4. Click **Install MCP in Cursor**. Your operating system asks if you want to
   open Cursor. Confirm. Cursor opens with the new server added to your
   user-level `mcp.json`.

5. Cursor opens a browser window for the gateway's OAuth flow. Sign in with your
   identity provider, complete the upstream connections on the consent page,
   then click **Authorize**.

6. Open **Cursor Composer** and verify the server's tools appear in the tool
   picker.

</Stepper>

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

```text
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:

```json title="~/.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:

```json
{
  "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](./overview.mdx)
- Cursor's docs: [Model Context Protocol](https://cursor.com/docs/context/mcp)
- [Authentication overview](../auth/overview.mdx)