# Connect Codex CLI ## 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: 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://vooi-api-app.fly.dev/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://vooi-api-app.fly.dev/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://vooi-api-app.fly.dev/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://vooi-api-app.fly.dev/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://vooi-api-app.fly.dev/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.**
--- # 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-codex-cli.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.