> ## Documentation Index
> Fetch the complete documentation index at: https://apixo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Troubleshooting: Fix Setup and Connection Issues
> Fix APIXO MCP browser setup, client connection, Node.js, and advanced API key configuration issues.
Start with the browser setup flow: register the MCP server, call `apixo_setup`, sign in and approve in the browser, then call `apixo_finish_setup`. The checks below follow that order.
## Browser setup did not open or finish
**Symptom.** `apixo_setup` returns `PENDING_APPROVAL`, but a browser does not open; or `apixo_finish_setup` reports that approval has not completed.
* **Open the returned URL yourself.** Use the `verification_url` from `apixo_setup` in a browser, sign in to APIXO, and approve the device.
* **Return to the same client conversation.** Call `apixo_finish_setup` after approval. If it still reports `PENDING_APPROVAL`, wait for the browser confirmation and try the tool again.
* **Start over after expiry.** If the approval expired, call `apixo_setup` again to begin a new browser approval.
* **Restart the client if needed.** Restart or reload the MCP client after changing its MCP configuration, then repeat the setup flow.
## A tool says the API key is missing or a request returns 401
**Symptom.** A model, generation, batch, or balance tool reports that setup is incomplete, the API key is missing, or the request is unauthorized.
1. Call `apixo_setup`, complete the browser sign-in and approval, then call `apixo_finish_setup`.
2. If the device key was revoked in [Dashboard → API Keys](https://apixo.ai/dashboard/api-keys), repeat browser setup to authorize a new device key.
3. If the client still uses a stale local credential after a revocation, remove that local credential only as local cleanup and restart the client before setting up again. This does **not** revoke or log out the device on the APIXO service; Dashboard key revocation is the formal server-side action.
4. If this is CI, a browserless environment, or a local debugging session, use the advanced `APIXO_API_KEY` override described in [Installation](/docs/integrations/mcp/installation#advanced-manually-supply-apixo_api_key).
## CLI not found on PATH
**Symptom.** Step 1 of [Installation](/docs/integrations/mcp/installation#step-1-register-the-mcp-server) fails with `codex : 无法将"codex"项识别为 cmdlet…` on Windows, or `command not found: codex` (or `claude`) on macOS or Linux.
The steps below use Codex on Windows as the example. For Claude Code, find its install folder, add it to PATH, and open a fresh terminal.
### Confirm Codex is installed (Windows)
Run the executable by full path. A per-user Codex installation commonly uses `%LOCALAPPDATA%\OpenAI\Codex\bin`:
```powershell theme={null}
& "C:\Users\YOUR_USER\AppData\Local\OpenAI\Codex\bin\codex.exe" --version
```
If this prints a version number, the binary is installed and only the PATH entry is missing.
### Add the Codex bin folder to your user PATH (Windows)
```powershell theme={null}
$codexBin = "C:\Users\YOUR_USER\AppData\Local\OpenAI\Codex\bin"
$userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
if ($userPath -notlike "*$codexBin*") {
[Environment]::SetEnvironmentVariable('Path', "$userPath;$codexBin", 'User')
}
```
Close the terminal, open a new one, and verify:
```powershell theme={null}
codex --version
```
Then repeat [Step 1](/docs/integrations/mcp/installation#step-1-register-the-mcp-server).
## `npx` cannot fetch `@apixo/mcp-server`
**Symptom.** The server fails to start with `npm ERR! 404 Not Found` or an `npx` network timeout.
* **Check Node.js and npm.** APIXO MCP requires Node.js `>= 20` and npm `>= 9`:
```bash theme={null}
node --version
npm --version
```
* **Verify the package resolves.** Run:
```bash theme={null}
npm view @apixo/mcp-server version
```
If it fails, check your npm registry with `npm config get registry`. It should be `https://registry.npmjs.org/` or a mirror that proxies it.
* **Pre-warm the package cache.** Run:
```bash theme={null}
npx -y @apixo/mcp-server --help
```
The next client launch can use the cached package.
## No tools listed in the client
**Symptom.** The `apixo` server appears in your client but no tools are available.
* Wait a few seconds, then refresh the client. The first launch may need to download the package.
* Inspect the MCP server logs in the client settings. Look for messages from `apixo-mcp-server` and correct a Node.js or `npx` error first.
* Check the registration from a terminal when your client provides a CLI. For example:
```bash theme={null}
codex mcp get apixo
```
* Restart the MCP client after the server starts successfully.
## Still stuck?
* Re-read [Installation](/docs/integrations/mcp/installation) and repeat the flow from registration through `apixo_finish_setup`.
* Confirm you can sign in to the APIXO Dashboard in the browser.
* Contact [APIXO support](https://apixo.ai/dashboard) with the client log, `node --version`, `npm --version`, and the output of `npx -y @apixo/mcp-server --help`. Never include an API key, MCP token, or credential file contents.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.