# Connect Claude Code ## 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: 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://vooi-api-app.fly.dev/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://vooi-api-app.fly.dev/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://vooi-api-app.fly.dev/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://vooi-api-app.fly.dev/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://vooi-api-app.fly.dev/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://vooi-api-app.fly.dev/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://vooi-api-app.fly.dev/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://vooi-api-app.fly.dev/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://vooi-api-app.fly.dev/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.** --- # 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-code.md?ask= ``` 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.