Connect Cursor

Configure Cursor to use VOOI MCP tools

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://perps-api.vooi.io/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://perps-api.vooi.io/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://perps-api.vooi.io/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://perps-api.vooi.io/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://perps-api.vooi.io/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.