Configuring Vortex MCP

Most of Vortex MCP is configured through a few environment variables plus the scan options you pass when you start a pentest.

Environment variables

Variable	Purpose
BD_PENTEST_API_URL	Your BestDefense pentest resource server, e.g. https://pentest.app.bestdefense.io or a dedicated-stack URL. Required.
BD_PENTEST_TOKEN	The scoped organization API token (scope pentest:run). Required on the default token path; omitted in device-flow secure mode.

In the Claude Code plugin these map to the api_url and api_token config fields. For a direct-MCP or CI setup you set the variables yourself — see Installation.

Note

The container also writes a durable log to the host. In the plugin install that’s ${CLAUDE_PLUGIN_DATA}/logs/bd-pentest-mcp.log. Set BD_PENTEST_LOG_LEVEL=DEBUG for more detail. Read the log file for diagnostics — never docker logs/exec a running scan container (see Running a pre-commit pentest).

Reaching your local app

Inside the container, localhost is the container itself, not your host. Address your locally-served app with host.docker.internal:

http://host.docker.internal:3000

The --add-host=host.docker.internal:host-gateway argument in the launch config makes this resolve to your host. There is a best-effort auto-rewrite from localhost to host.docker.internal, but don’t rely on it — pass host.docker.internal explicitly.

Scan modes

Pass a mode when you start a pentest:

Mode	Depth	Billing
smoke	Fast, diff-scoped pre-commit check	Seat-covered
standard	The default, balanced pass	Seat-covered
deep	The most thorough pass	Reserves a pre-commit credit

If you don’t pass a mode, standard is used.

Test profiles

Pass a test_profile to control how much local context the pentest starts with:

• blackbox (default) — the pentester works only from the target URL, like an external attacker.
• greybox — the executor derives the attack surface (routes, OpenAPI, tech-stack) locally from your workdir and sends only that derived context to the brain. Your source code never leaves your machine; only the derived surface does.

For greybox, set workdir to your repo root (it defaults to the current working directory). If derivation fails, the scan falls back to blackbox and continues.

See Running a pre-commit pentest for the full flow and Tools reference for exact parameters.