Troubleshooting Vortex MCP

Most Vortex MCP problems fall into a handful of categories. Run /bestdefense-pentest:doctor first — it names the failing layer and prints the remedy. The details below explain each one.

The scan can’t reach my app

The container’s localhost is the container, not your host. Address your local app with host.docker.internal:

http://host.docker.internal:3000   ✅
http://localhost:3000              ❌ (resolves inside the container)

There’s a best-effort auto-rewrite, but pass host.docker.internal explicitly to be sure. See Configuration.

Login fails or hangs on WSL2 / headless Linux {#wsl2—headless-keychain}

Device-flow secure mode stores its refresh token in the OS keychain. macOS Keychain and Windows Credential Manager work out of the box, but headless Linux and WSL2 have no keychain by default, so login fails with “no OS keychain backend is available” or hangs.

The simplest fix is to use the default API-token path, which needs no keychain at all. If you specifically want secure mode, set up a Secret Service once:

sudo apt-get install -y gnome-keyring
python3 -m pip install --user keyring secretstorage
eval "$(printf '' | gnome-keyring-daemon --unlock --components=secrets)"
python3 -c "import keyring; print(keyring.get_keyring())"   # must print SecretService

The first login afterward may prompt to create a keyring — leave the password fields empty to get an auto-unlocking default. See the setup skill for the full WSLg walkthrough.

A direct GET …/findings returns 404

This is by design. Status and findings are delivered through the MCP tools (get_pentest_status, get_findings), not a public REST path. Use the tools; a direct HTTP GET to a findings URL will always 404.

Vortex MCP isn’t enabled for your organization

If a scan reports that the pre-commit pentest isn’t enabled for your org, confirm your organization has the Vortex MCP add-on active and that your own seat is enabled. The add-on is a standalone subscription and does not require a Vortex plan, so a missing Vortex plan is never the cause here. If you’re unsure, contact your org admin — they enable seats under Members.

A long scan fails partway with an auth error

On the static token path, a token that ages out mid-scan can cause a long-running deep scan to fail. Regenerate the org token, or switch to device-flow secure mode, whose token broker mints a fresh ≤ 900-second access token per request and refreshes automatically across a long session. See Authentication.

Don’t kill the scan container

If a scan seems stuck, keep polling get_pentest_status — don’t docker logs/exec, restart, or tail the container. The executor runs inside that container, so touching it aborts the scan and loses findings. Read the host log file (${CLAUDE_PLUGIN_DATA}/logs/bd-pentest-mcp.log) for diagnostics instead.