Connect Codex CLI

Configure Codex CLI to use VOOI MCP tools

Overview

This guide explains how to connect the VOOI MCP server to Codex CLI.

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

Codex CLI supports remote MCP servers over HTTP. The VOOI MCP server uses a remote HTTP endpoint and Bearer token authentication.

The same Codex configuration can also be used by the Codex IDE extension if it reads the same configuration file.

Requirements

Before you start, make sure you have:

• Codex CLI installed

• a VOOI API token

• access to a terminal

• permission to edit your Codex configuration

Check that Codex CLI is installed:

codex --version

If Codex CLI is not installed, install it first using the official Codex 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 Codex 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 in Codex CLI:

codex mcp add vooi-perps \  --url https://perps-api.vooi.io/mcp \  --bearer-token-env-var VOOI_API_TOKEN

This command adds a server named vooi-perps.

Codex 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

Verify the connection

List configured MCP servers:

codex mcp list

You should see vooi-perps in the list.

To inspect the server configuration:

codex mcp get vooi-perps --json

The output should show the MCP server URL and the environment variable name. It should not expose the raw token.

Use VOOI tools in Codex

Start a Codex session:

codex

VOOI tools should be available alongside the built-in Codex tools.

You can test the connection with a prompt such as:

List my open VOOI perpetual positions and their PnL.

Manual configuration

You can also add the server manually by editing the Codex config file.

Global config:

~/.codex/config.toml

Project-scoped config:

.codex/config.toml

Add the following block:

[mcp_servers.vooi-perps]url = "https://perps-api.vooi.io/mcp"bearer_token_env_var = "VOOI_API_TOKEN"

Use mcp_servers with an underscore.

After editing the file, restart the Codex session.

Project-scoped configuration

To make VOOI MCP available only inside a specific project, create or edit this file inside the project directory:

.codex/config.toml

Add the same server block:

[mcp_servers.vooi-perps]url = "https://perps-api.vooi.io/mcp"bearer_token_env_var = "VOOI_API_TOKEN"

Use this option when the VOOI MCP server should be available only in one trusted project.

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 config files that contain hard-coded tokens

• store the token in public or unprotected synced folders

Use bearer_token_env_var 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 is listed, but tools do not appear

Start Codex with debug logs:

codex --log-level 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 Codex is running

• the MCP endpoint is not reachable

• the server timed out during startup

Token is not available to Codex

Check the variable in the same terminal session where you run Codex:

echo $VOOI_API_TOKEN

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

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

Connection refused or timeout

If Codex 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.

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 Codex.

If the variable is set but the error remains, generate a new VOOI API token and update VOOI_API_TOKEN.

Config syntax error

If Codex fails after manual config changes, check config.toml for syntax errors.

Common issues include:

• missing quotes around string values

• incorrect section name

• invalid TOML formatting

Make sure the config block uses this section name:

[mcp_servers.vooi-perps]

Remove the server

To remove the VOOI MCP server from Codex:

codex mcp remove 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 codex mcp get vooi-perps --json

• relevant lines from codex --log-level debug

• your Codex CLI version

Do not send your raw VOOI API token.