toolbox

The toolbox MCP server implements a hands-on security testing workbench that coordinates with agents to explore, mutate, and validate application behavior. It exposes a native proxy and a set of tools described in the toolbox suite, including a wire-fidelity proxy for intercepting traffic, replay with mutation capabilities, flow diffing, reflection detection, and out-of-band interaction testing. Operators collaborate with the agent by using the command set to review proxy history, crawl applications for endpoints, replay modified requests, and test for callbacks from out-of-band channels, all while maintaining session state through the MCP connection.

To use the toolbox server, start it (for example via Docker as configured in the MCP setup) and point your agents to the MCP endpoint at /mcp. The agent can query proxy history, replay requests with modifications, crawl applications to discover endpoints and forms, and perform out-of-band testing. The workflow system guides the agent's actions (explore, test-report, or none) to balance automation with humanExpertise, enabling collaborative testing with minimal token waste. If desired, enable notes to attach observations to flows, and consider Burp as a GUI frontend if you prefer external review alongside the native toolbox proxy.

Key capabilities you can leverage include: a wire-fidelity proxy supporting HTTP/1.1, HTTP/2, and WebSocket; replay with mutation to adjust headers, body, or query parameters; structured flow diffing for quick validation; reflection detection across responses; Interactsh-based out-of-band testing; crawling to uncover endpoints; and encoding utilities for rapid data manipulation. Combine these tools with your browser-based actions for authentication and UI testing, while the agent performs automated tasks against the captured traffic.

Prerequisites:

• Docker (or a compatible container runtime) installed on the machine hosting the MCP server
• Optional: Go toolchain if you prefer building or running a local binary instead of Docker
• Access to the MCP framework and the toolbox container image (go-appsec/toolbox)

Option A: Run Toolbox via Docker (recommended for MCP deployments)

1. Install Docker from https://www.docker.com/
2. Pull and run the toolbox image (the MCP server configuration will handle the MCP endpoints): docker run -d --name toolbox-mcp -p 9119:9119 -p 8080:8080 go-appsec/toolbox
3. Confirm the MCP server is accessible at http://localhost:9119/mcp

Option B: Build and run locally (if you prefer a direct Go binary)

1. Install Go (1.20+): https://go.dev/dl/
2. Clone the toolbox repository: git clone https://github.com/go-appsec/toolbox.git
3. Build the binary (example assumes a go module layout within the repo): cd toolbox go build ./...
4. Run the MCP server from the binary (adjust paths as needed): ./toolbox mcp
5. Ensure the server listens on port 9119 and proxies on 8080 by default, or configure as needed.

Configuration tip: If you use the Docker approach, ensure any required environment variables (e.g., proxy settings, certificates) are passed via -e VAR=VALUE or a suitable docker-compose file depending on your environment.

Notes and tips:

• The MCP server exposes two endpoints: /mcp (streamable HTTP) and /sse (legacy SSE). Use /mcp for modern clients.
• By default, the toolbox proxy runs on port 8080 and the MCP server on 9119; adjust via your docker run options or environment as needed.
• If integrating with Burp, you can run the Burp MCP extension and point it to http://127.0.0.1:9119/mcp. The native proxy remains usable as a headless backend.
• Enable the notes feature with the appropriate workflow by using the --notes flag to save observations linked to flows; this is helpful for longer sessions with many findings.
• For agent collaboration, ensure the mcp transport path is accessible from the agent (e.g., http://host:9119/mcp). Network/firewall rules should permit this traffic.
• When debugging, check the container logs (docker logs toolbox-mcp) for startup messages and proxy binding details.