Connect Claude Desktop

Configure Claude Desktop to use VOOI MCP tools

Overview

This guide explains how to connect the VOOI MCP server to Claude Desktop.

After setup, VOOI tools will be available in Claude Desktop, allowing the assistant to interact with VOOI Perps through the MCP server.

Claude Desktop uses local MCP server configuration. Because VOOI MCP is a remote HTTP server, this setup uses mcp-remote as a local bridge between Claude Desktop and the VOOI MCP endpoint.

Important note

Claude Desktop’s Custom Connectors UI currently supports OAuth authentication for remote MCP servers.

VOOI MCP uses static Bearer token authentication. For this reason, VOOI MCP should be added through the local Claude Desktop configuration file, using mcp-remote to connect Claude Desktop to the remote VOOI MCP endpoint.

Requirements

Before you start, make sure you have:

• Claude Desktop installed

• Node.js installed

• a VOOI API token

• permission to edit the Claude Desktop MCP configuration

Check that Node.js is installed:

node --version

If Node.js is not installed, install the LTS version from nodejs.org.

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.

Open the Claude Desktop config file

In Claude Desktop, open: Settings → Developer → Edit Config

This opens or creates the Claude Desktop MCP configuration file.

Default config file paths:

macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json

Add the VOOI MCP server

Add the following server block to claude_desktop_config.json:

{  "mcpServers": {    "vooi-perps": {      "command": "npx",      "args": [        "-y",        "mcp-remote@latest",        "https://perps-api.vooi.io/mcp",        "--header",        "Authorization: Bearer ${VOOI_API_TOKEN}"      ],      "env": {        "VOOI_API_TOKEN": "vooi_your_token_here"      }    }  }}

Replace vooi_your_token_here with your VOOI API token.

This configuration starts mcp-remote with npx and connects Claude Desktop to the VOOI MCP endpoint:

https://perps-api.vooi.io/mcp

The token is passed to the VOOI MCP server as a Bearer token in the Authorization header.

Restart Claude Desktop

After editing the config file, save it and fully restart Claude Desktop.

Closing the window may not be enough.

On macOS, quit the app with:

Cmd + Q

On Windows, quit Claude Desktop from the tray icon.

Then start Claude Desktop again.

Verify the connection

Open a new Claude Desktop chat.

Open the tools menu and check that vooi-perps is available.

You can test the connection with a prompt such as:

List my open VOOI perpetual positions and their PnL.

If the server is connected correctly, Claude Desktop should be able to access the VOOI MCP tools.

Multiple MCP servers

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

Example:

{  "mcpServers": {    "filesystem": {      "command": "npx",      "args": [        "-y",        "@modelcontextprotocol/server-filesystem",        "/Users/you/Projects"      ]    },    "vooi-perps": {      "command": "npx",      "args": [        "-y",        "mcp-remote@latest",        "https://perps-api.vooi.io/mcp",        "--header",        "Authorization: Bearer ${VOOI_API_TOKEN}"      ],      "env": {        "VOOI_API_TOKEN": "vooi_your_token_here"      }    }  }}

Make sure the JSON syntax is valid. A missing brace, missing comma, or trailing comma can prevent Claude Desktop 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 config files with raw tokens to git

• share claude_desktop_config.json if it contains a token

• store the token in public or unprotected synced folders

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

Troubleshooting

Server does not appear in Claude Desktop

Open: Settings → Developer

Check whether the server is listed and whether Claude Desktop shows an error.

Then check the MCP logs.

Default log file paths:

macOS:~/Library/Logs/Claude/mcp-server-vooi-perps.logWindows:%APPDATA%\Claude\logs\mcp-server-vooi-perps.logLinux:~/.config/Claude/logs/mcp-server-vooi-perps.log

Common causes:

• invalid JSON in claude_desktop_config.json

• Node.js or npx is not available to Claude Desktop

• Claude Desktop was not fully restarted

• the VOOI API token is missing or invalid

• the MCP endpoint is not reachable

401 Unauthorized

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

Check that the token in the env block is correct:

"env": {  "VOOI_API_TOKEN": "vooi_your_token_here"}

Also check that the header uses the same variable name:

"Authorization: Bearer ${VOOI_API_TOKEN}"

The variable name is case-sensitive.

Connection refused or timeout

If Claude Desktop 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.

Invalid JSON

If Claude Desktop stops showing all MCP servers after editing the config, the JSON file may be invalid.

Common issues include:

• trailing commas

• missing commas between fields

• missing closing braces

• unescaped special characters in the token

Validate claude_desktop_config.json with a JSON validator and restart Claude Desktop after fixing the file.

Remove the server

To remove VOOI MCP from Claude Desktop, delete the vooi-perps block from claude_desktop_config.json.

Then save the file and restart Claude Desktop.

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:

• relevant lines from mcp-server-vooi-perps.log

• your claude_desktop_config.json with the token replaced by ***

• your Claude Desktop version

• your Node.js version

Do not send your raw VOOI API token.