Skip to content
BestDefense Docs

Installing Vortex MCP

There are two ways to install Vortex MCP: the Claude Code plugin (the smoothest path) or a direct MCP server configuration for any other MCP client or CI. Both run the same container.

Claude Code plugin

Section titled “Claude Code plugin”

1. Add the marketplace and install

Section titled “1. Add the marketplace and install”

Run these in Claude Code:

/plugin marketplace add BestDefense-io/bd-pentest-plugin
/plugin install bestdefense-pentest@bestdefense

Pick a scope when prompted (User / Project / Local).

2. Run one-time setup

Section titled “2. Run one-time setup”
/bestdefense-pentest:bd-pentest-setup

This walks you through authentication and connectivity. Configure your token under /plugin → configure (see Authentication). Dedicated-stack customers set api_url here too, e.g. https://pentest.<your-stack>.bestdefense.io.

3. Confirm you’re ready

Section titled “3. Confirm you’re ready”
/bestdefense-pentest:doctor

The preflight checks Docker, the executor image, your token, org entitlement, and (optionally) target reachability in one pass. Fix anything it marks FAIL — each line prints its remedy — before scanning.

Version pinning and updates

Section titled “Version pinning and updates”

The plugin’s .mcp.json pins an exact image tag and pulls it only if it’s missing:

"args": ["run", "-i", "--rm", "--pull=missing", "...",
         "ghcr.io/bestdefense-io/bd-pentest-mcp:0.1.19"]

The current tag is 0.1.19. --pull=missing means the image is fetched once and reused; a new plugin version bumps the pinned tag, so updating the plugin is how you get a new executor. To force a re-pull of a tag you already have:

Terminal window
docker pull ghcr.io/bestdefense-io/bd-pentest-mcp:0.1.19

Direct MCP server (any client or CI)

Section titled “Direct MCP server (any client or CI)”

The server is plain MCP over stdio. In any MCP client — or a CI job — register a server that runs the container with your token. This is the same shape the plugin uses:

{
  "mcpServers": {
    "bestdefense-pentest": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--pull=missing",
        "--cap-add=NET_ADMIN",
        "--add-host=host.docker.internal:host-gateway",
        "-e", "BD_PENTEST_API_URL",
        "-e", "BD_PENTEST_TOKEN",
        "ghcr.io/bestdefense-io/bd-pentest-mcp:0.1.19"
      ],
      "env": {
        "BD_PENTEST_API_URL": "https://pentest.app.bestdefense.io",
        "BD_PENTEST_TOKEN": "<org API token>"
      }
    }
  }
}

Keep --cap-add=NET_ADMIN — it lets the container enforce its own outbound-network guardrails during a scan. The Claude Code plugin adds this for you automatically.

Use host.docker.internal (not localhost) to reach your local app — see Configuration. This same configuration is what you use for CI integration.