Troubleshooting & FAQ
Most Proxima problems come from one of four places: the editor's MCP config file, the Proxima desktop app not running, an expired provider login, or the Python environment used by the optional agent. This page lists the symptoms we see most often, what causes each one, and how to confirm the fix.
Quick diagnosis
1. How the pieces connect
Knowing the path a request takes makes every other fix on this page easier to reason about. Your editor starts src/mcp/index.js as a child process and talks to it over standard input and output. That Node process does not call any AI model itself. It forwards each tool call to the Proxima desktop app over a local socket on port 19222. The desktop app then sends the prompt either through a logged-in provider tab (Session Mode) or through an API key or local endpoint (BYOK Mode).
Two local ports are involved, and both bind to 127.0.0.1 only, so neither is reachable from another machine:
19222(default): the bridge between the MCP process and the desktop app. Always used when you connect from an editor. If the port is taken, the MCP process scans a small range of nearby ports, and the environment variableAGENT_HUB_PORTsets the starting value.3210(default): the optional OpenAI-compatible REST API and WebSocket. Used by the CLI, the SDKs and your own scripts, and only after you enable it in Settings. Since 5.5.0, if 3210 is busy Proxima uses the next free port and records it inrest-port.json.
The practical consequence: the editor can show a connected server while the desktop app is closed, because the editor only knows that the Node process started. Always test with a real tool call, as described in the Windsurf guide (the same three test prompts work in any editor).
2. The server does not appear in my editor
- Check the JSON. One trailing comma makes the whole file unparseable, and editors usually fail silently, so servers that worked yesterday vanish too.
- Check the top-level key. Cursor, Windsurf, Claude Desktop and Cline use
mcpServers. VS Code's ownmcp.jsonusesserversand requires"type": "stdio". See the VS Code guide. - Use forward slashes on Windows. Write
C:/Users/you/Proxima/src/mcp/index.js. In JSON a single backslash is an escape character, soC:\Users\...breaks the path (\Uis invalid). - Check Node. Run
node --version. The MCP server needs Node.js 18 or newer. If the editor was launched from a shortcut, it may not inherit the PATH from your terminal, so put the absolute path to the node binary incommand. - Restart the editor after saving. Most editors read the MCP file only at startup or when you reload the window.
You can also run the server by hand to see the real error. In a terminal, run node C:/path/to/Proxima/src/mcp/index.js. It should start and wait for input without printing an error. A "cannot find module" message means the path or the installation is wrong. Press Ctrl+C to stop it.
3. The server is listed, but tool calls fail or return nothing
- Is the desktop app running? If it is closed, the bridge on port 19222 has nothing to connect to.
- Is the provider still logged in? In Session Mode, Proxima uses the same kind of browser session you would use in Chrome. Sessions expire, get challenged by the provider (for example a CAPTCHA), or are logged out when you change a password. Open the provider's tab inside Proxima and sign in again.
- Separate the layers.
ddg_searchneeds no provider session. If it works whileask_claudedoes not, your editor configuration is fine and the problem is the provider login. - Try another provider.
ask_all_aisqueries every enabled provider at once, which shows quickly whether one provider is failing or all of them are. - "Model not available" errors (5.5.0 and later). Proxima no longer swaps in a different model when you name one that your account does not have. Call
list_available_models(or runproxima models, or openGET /v1/models) and use a slug from that list, such asgemini:pro. Model lists depend on your plan, so a name that works on one account can be missing on another. Passrefresh: truetolist_available_modelsif you just upgraded your plan or logged in again.
4. Python agent: "Python 3.10+ Environment" shows Error or Missing
Python is only needed for the optional Proxima Agent. The MCP bridge and the REST API do not use it. If the Diagnostics panel shows a red mark next to Python 3.10+ Environment although Python is installed, there are two usual causes.
Cause A: the app folder is write-protected (older builds on Windows)
The installer places the app in C:\Program Files\Proxima, which standard users cannot write to. During first-time setup, pip install needs to write temporary files, fails with "Access is denied", and the check stays red. From version 5.0.0 the installer bundles a pre-built wheel that installs into the virtual environment without writing to the app folder, so this should not occur on a current build.
If you are on an older build:
On macOS and Linux the app directory is usually owned by your user, so this is rare. If it does happen, run the app once with sudo to finish the initial setup.
Cause B: Python is installed but not on PATH
- Windows: in the Python installer, tick Add Python.exe to PATH on the first screen. If you missed it, run the installer again, choose Modify, and enable the PATH option.
- macOS / Linux: run
python3 --version. If it is not found, install Python from python.org or your package manager. Proxima needs version 3.10 or higher.
5. REST API and WebSocket on port 3210 are refused
The REST API is off by default. Enable it in Proxima's Settings, then test with:
A JSON status reply means the server is up, and it includes the port it is bound to. If the connection is refused, check that the setting is on. The CLI and the Python and JavaScript SDKs all depend on this switch. The WebSocket endpoint (ws://localhost:3210/ws) is part of the same server, so it is available only when the REST API is enabled.
Proxima may have moved to a different port (5.5.0 and later)
If another program already uses 3210, Proxima tries the following ports (up to 20) instead of failing, and writes the port it got to rest-port.json. The official CLI, Python SDK, JavaScript SDK and agent read that file, so they keep working. A script that hard-codes localhost:3210 will not. To find the live port:
To pin the starting port, set PROXIMA_REST_PORT before launching Proxima, and set the same variable for your scripts.
Frequently asked questions
Is Proxima free?
The software itself costs nothing, and Session Mode uses the free accounts you already have with each provider, so no API key is required. If you choose BYOK Mode, you pay your API provider directly for the tokens you use. Proxima is released under a personal-use, non-commercial license. For commercial use, read the license and contact the author first.
Does Proxima see or store my prompts?
Proxima keeps its configuration, conversation vault and memory databases on your own machine, and does not send them to a Proxima server. Your prompts do go to whichever AI provider you route them to, exactly as they would if you typed them into that provider's website or API. For work where code must never leave your computer, use BYOK Mode with a local model through Ollama or LM Studio.
How does Session Mode work without storing my password?
Proxima opens each provider in an isolated browser view inside the app. You sign in there as you would in any browser, and the browser keeps the session cookie on your device. Proxima reuses that session to send prompts. It never asks for, or stores, your password.
Session Mode or BYOK Mode: which should I use?
Session Mode is the fast way to start and costs nothing extra, but it depends on provider web interfaces, which can change or add checks without notice. BYOK Mode uses official APIs or local endpoints, so it is steadier, supports fully offline models, and is the right choice for team or commercial work. You can switch between them in Settings at any time.
Can I run models completely offline?
Yes. BYOK Mode accepts any OpenAI-compatible endpoint, including Ollama and LM Studio running on your machine. See the blog guide on connecting local models for the setup.
Will the Python agent change my files without asking?
Not by default. The agent runs in Suggest or Smart mode, which show the proposed diff or command and wait for your approval before writing files or running anything. Full Auto mode skips that approval and is something you must switch on yourself.
Still stuck? How to report a problem
A report that includes the following can usually be answered in one reply:
- Your operating system and the Proxima version shown in the app.
- The editor you are using, and the exact contents of its MCP config entry (remove any API keys first).
- The output of
node --version, andpython --versionif the problem involves the agent. - What happened when you ran the three test prompts from the Windsurf guide.
Open an issue on the GitHub tracker, or use the contact page. For a security vulnerability, do not open a public issue: use GitHub Security Advisories as described in the repository's SECURITY.md.