# 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.

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](../quickstart.mdx) 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:

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

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

- **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)