Connect Claude Code

Configure Claude Code to use VOOI MCP tools

Overview

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

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

Claude Code 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:

• Claude Code installed

• a VOOI API token

• access to a terminal

• permission to edit your Claude Code configuration

Check that Claude Code is installed:

claude --version

If Claude Code is not installed, install it first using the official Claude Code installation instructions.

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 the Claude Code config file.

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"

Add the VOOI MCP server

Register the VOOI MCP server from a regular terminal.

Do not run this command from inside an active Claude Code session.

claude mcp add --transport http vooi-perps https://perps-api.vooi.io/mcp \  --header "Authorization: Bearer ${VOOI_API_TOKEN}"

This command adds a server named vooi-perps.

Claude Code 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

Choose a configuration scope

Claude Code supports different configuration scopes.

By default, the server is added for the current project.

Use the default scope if you want VOOI MCP to be available only in the current project.

claude mcp add --transport http vooi-perps https://perps-api.vooi.io/mcp \  --header "Authorization: Bearer ${VOOI_API_TOKEN}"

Use --scope user if you want VOOI MCP to be available in every Claude Code project for your user.

claude mcp add --transport http --scope user vooi-perps https://perps-api.vooi.io/mcp \  --header "Authorization: Bearer ${VOOI_API_TOKEN}"

Use --scope project if you want to add the server definition to the project configuration.

claude mcp add --transport http --scope project vooi-perps https://perps-api.vooi.io/mcp \  --header "Authorization: Bearer ${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.

Verify the connection

List configured MCP servers:

claude mcp list

You should see vooi-perps in the list.

To inspect the server configuration:

claude mcp get vooi-perps

The output should show the MCP server URL and the authorization header configuration. It should not expose the raw token if the token is provided through an environment variable.

Use VOOI tools in Claude Code

Start a Claude Code session:

claude

VOOI tools should be available alongside the built-in Claude Code tools.

You can test the connection with a prompt such as:

List my open VOOI perpetual positions and their PnL.

Manual project configuration

You can also add the server manually by editing .mcp.json in the project root.

Create or edit:

.mcp.json

Add the following configuration:

{  "mcpServers": {    "vooi-perps": {      "type": "http",      "url": "https://perps-api.vooi.io/mcp",      "headers": {        "Authorization": "Bearer ${VOOI_API_TOKEN}"      }    }  }}

Claude Code resolves ${VOOI_API_TOKEN} from the shell environment when the session starts.

The file itself should not contain the raw token.

After editing .mcp.json, start a new Claude Code session.

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": {      "type": "http",      "url": "https://perps-api.vooi.io/mcp",      "headers": {        "Authorization": "Bearer ${VOOI_API_TOKEN}"      }    },    "sentry": {      "type": "http",      "url": "https://mcp.sentry.dev/mcp"    }  }}

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

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 .mcp.json files that contain raw tokens

• store the token in public or unprotected synced folders

Use environment variables whenever possible, so config files contain only the variable name.

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

Troubleshooting

Server is listed, but tools do not appear

Start Claude Code with debug logs:

claude --debug

Look for entries related to vooi-perps.

Common causes:

• the token is missing or expired

• VOOI_API_TOKEN is not available in the shell where Claude Code is running

• the MCP endpoint is not reachable

• the server timed out during startup

Token is not available to Claude Code

Check the variable in the same terminal session where you run Claude Code:

echo $VOOI_API_TOKEN

If the output is empty, export the token again and restart Claude Code.

For persistent setup, add the export line to your shell profile and open a new terminal session.

401 Unauthorized

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

Check that the environment variable is set:

echo $VOOI_API_TOKEN

If the variable is empty, set it again and restart Claude Code.

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 Claude Code 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 in .mcp.json

If a project-scoped server does not load, check .mcp.json for syntax errors.

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 start a new Claude Code session after fixing the file.

Header parsing issues on Windows

On some Windows setups, the --header argument may not parse correctly in cmd.exe.

Use PowerShell instead, or add the server through JSON configuration.

Example:

claude mcp add-json vooi-perps '{"type":"http","url":"https://perps-api.vooi.io/mcp","headers":{"Authorization":"Bearer YOUR_TOKEN_HERE"}}'

This method may require using the token directly in the command. Prefer the environment variable setup when possible.

Remove the server

To remove the VOOI MCP server from Claude Code:

claude mcp remove vooi-perps

If you added the server with a specific scope, remove it with the matching scope.

For user scope:

claude mcp remove --scope user vooi-perps

For project scope:

claude mcp remove --scope project vooi-perps

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:

• the output of claude mcp get vooi-perps

• relevant lines from claude --debug

• your Claude Code version

Do not send your raw VOOI API token.