# Connect Claude Desktop

## 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://vooi-api-app.fly.dev/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://vooi-api-app.fly.dev/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://vooi-api-app.fly.dev/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://vooi-api-app.fly.dev/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.**


---

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