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

CLI not found on PATH

Symptom. Step 1 of Installation 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:

& "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)

$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:

codex --version

Then repeat Step 1.

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:

  node --version
  npm --version
  

• Verify the package resolves. Run:

  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:

  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:

  codex mcp get apixo
  

• Restart the MCP client after the server starts successfully.

Still stuck?

• Re-read 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 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.