# Connect Cursor

## Overview

This guide explains how to connect the VOOI MCP server to Cursor.

After setup, VOOI tools will be available in Cursor, allowing the agent to interact with VOOI Perps through the MCP server.

Cursor supports remote MCP servers over HTTP. Because of this, VOOI MCP can be connected directly. No `mcp-remote` bridge is required.

## Requirements

Before you start, make sure you have:

* Cursor installed
* Cursor version `0.48.0` or later
* a VOOI API token
* permission to edit Cursor MCP configuration

Check your Cursor version in: Cursor → About

## Get a VOOI API token

Generate a VOOI API token from the VOOI Ultra user token page:

<https://ultra.vooi.io/api-tokens>

Copy the token immediately and store it securely. The token may not be shown again after you close the page.

## Store the token as an environment variable

Store the token in an environment variable instead of writing it directly into `mcp.json`.

For macOS or Linux:

```
export VOOI_API_TOKEN="vooi_your_token_here"
```

To make the variable available in future terminal sessions, add the same line to your shell profile.

Common shell profile files:

```
~/.zshrc~/.bashrc~/.bash_profile
```

For Windows PowerShell:

```
$env:VOOI_API_TOKEN = "vooi_your_token_here"
```

Cursor must be able to read this environment variable when it starts.

If you set the variable in a terminal but launch Cursor from the Dock, Start menu, or another launcher, Cursor may not see it. In that case, set the variable system-wide or start Cursor from a shell where `VOOI_API_TOKEN` is available.

## Open Cursor MCP settings

In Cursor, open: Settings → Tools & Integrations → MCP Tools → Add Custom MCP

This opens or creates the Cursor MCP configuration file.

Depending on your Cursor version, the button may also be called:

```
New MCP Server
```

## Add the VOOI MCP server

Add the following configuration to `mcp.json`:

```
{  "mcpServers": {    "vooi-perps": {      "url": "https://vooi-api-app.fly.dev/mcp",      "headers": {        "Authorization": "Bearer ${env:VOOI_API_TOKEN}"      }    }  }}
```

This adds a server named `vooi-perps`.

Cursor will read the token from `VOOI_API_TOKEN` and send it as a Bearer token when connecting to the VOOI MCP server.

The VOOI MCP endpoint is:

```
https://vooi-api-app.fly.dev/mcp
```

## Restart Cursor

After editing `mcp.json`, save the file and fully restart Cursor.

Closing the window may not be enough. Quit Cursor from the menu and start it again.

## Verify the connection

Open: Settings → Tools & Integrations → MCP Tools

You should see `vooi-perps` in the MCP tools list.

A green dot means the server is connected.

You can also check MCP logs in:

```
View → Output → MCP
```

You can test the connection with a prompt such as:

```
List my open VOOI perpetual positions and their PnL.
```

## Global and project configuration

Cursor supports global and project-level MCP configuration.

Global config paths:

```
macOS / Linux:~/.cursor/mcp.jsonWindows:%USERPROFILE%\.cursor\mcp.json
```

Project config path:

```
.cursor/mcp.json
```

Use global configuration if you want VOOI MCP to be available across Cursor projects.

Use project configuration if you want VOOI MCP to be available only inside a specific workspace.

If the same server name exists in both global and project configuration, the project-level configuration takes priority.

## Project-scoped configuration

To make VOOI MCP available only inside a specific project, create or edit:

```
.cursor/mcp.json
```

inside the project root.

Add the same configuration:

```
{  "mcpServers": {    "vooi-perps": {      "url": "https://vooi-api-app.fly.dev/mcp",      "headers": {        "Authorization": "Bearer ${env:VOOI_API_TOKEN}"      }    }  }}
```

For shared project configuration, do not hard-code a raw token. Each developer should set their own `VOOI_API_TOKEN` environment variable.

## Multiple MCP servers

If you already have other MCP servers configured, add `vooi-perps` alongside them inside the same `mcpServers` object.

Example:

```
{  "mcpServers": {    "vooi-perps": {      "url": "https://vooi-api-app.fly.dev/mcp",      "headers": {        "Authorization": "Bearer ${env:VOOI_API_TOKEN}"      }    },    "filesystem": {      "command": "npx",      "args": [        "-y",        "@modelcontextprotocol/server-filesystem",        "/Users/you/Projects"      ]    }  }}
```

Make sure the JSON syntax is valid. A missing brace, missing comma, or trailing comma can prevent Cursor from loading MCP servers.

## Token security

Keep your VOOI API token private.

Do not:

* paste the token into chats, screenshots, logs, or support messages
* commit `mcp.json` with a raw token to git
* share config files that contain raw tokens
* store the token in public or unprotected synced folders

Use `${env:VOOI_API_TOKEN}` whenever possible, so the config file contains only the environment variable name.

If a token is exposed, revoke it and generate a new one.

## Troubleshooting

### Server shows a red dot or failed connection

If `vooi-perps` shows a red dot, open the server entry in:

```
Settings → Tools & Integrations → MCP Tools
```

Check the error message.

Also check MCP logs in: View → Output → MCP

Common causes:

* the token is missing or expired
* `VOOI_API_TOKEN` is not available to Cursor
* the MCP endpoint is not reachable
* the Cursor version is too old
* the JSON configuration is invalid

### Token is not available to Cursor

Check whether the token is available in the environment where Cursor starts.

For macOS or Linux:

```
echo $VOOI_API_TOKEN
```

For Windows PowerShell:

```
echo $env:VOOI_API_TOKEN
```

If the output is empty, set the variable again and restart Cursor.

If Cursor was launched from the Dock, Start menu, or another launcher, it may not read variables set only in a terminal session.

In that case, set the variable system-wide or start Cursor from a terminal where `VOOI_API_TOKEN` is available.

### 401 Unauthorized

A `401 Unauthorized` error usually means the token is missing, expired, or malformed.

Check that the header uses the correct environment variable name:

```
"Authorization": "Bearer ${env:VOOI_API_TOKEN}"
```

Then check that `VOOI_API_TOKEN` is set and available to Cursor.

If the variable is set but the error remains, generate a new VOOI API token and update `VOOI_API_TOKEN`.

### Connection refused or timeout

If Cursor cannot reach the VOOI MCP server, check your network connection.

You can test the endpoint from a terminal:

```
curl -I https://vooi-api-app.fly.dev/mcp
```

A VPN, proxy, firewall, or DNS filter can block the endpoint.

### Server connects, but tools do not appear

If the server has a green dot but tools do not appear, check: View → Output → MCP

Possible causes:

* tool enumeration failed
* Cursor version is too old
* too many MCP tools are enabled across all configured servers

If many MCP servers are active, disable the ones you are not using and restart Cursor.

### Invalid JSON

If Cursor stops showing MCP servers after editing `mcp.json`, the JSON file may be invalid.

Common issues include:

* trailing commas
* missing commas between fields
* missing quotes around string values
* missing closing braces

Validate `mcp.json` with a JSON validator and restart Cursor after fixing the file.

### .cursor folder does not exist

On a fresh Cursor installation, the `.cursor` folder may not exist yet.

You can create it manually.

For macOS or Linux:

```
mkdir -p ~/.cursor && touch ~/.cursor/mcp.json
```

For Windows PowerShell:

```
New-Item -Path "$env:USERPROFILE\.cursor" -ItemType Directory -ForceNew-Item -Path "$env:USERPROFILE\.cursor\mcp.json" -ItemType File
```

Then add the VOOI MCP configuration to `mcp.json`.

## Remove the server

To remove VOOI MCP from Cursor, delete the `vooi-perps` block from `mcp.json`.

Then save the file and restart Cursor.

You can also remove the server from: Settings → Tools & Integrations → MCP Tools

If you no longer plan to use the token, revoke it in your VOOI account.

## Need help?

If you contact VOOI support about MCP connection issues, include:

* your `mcp.json` content with the token replaced by `***`
* relevant lines from `View → Output → MCP`
* your Cursor version

**Do not send your raw VOOI API token.**


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.vooi.io/vooi-ultra-v3/vooi_ultra-mcp/connect-cursor.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.