MCP server agentic-pentest-proxy

Agentic Pentesting MCP Gateway

New to the gateway? The documentation site shows the local and hosted paths side by side, including where test traffic comes from. The full guides below are also available there after team sign-in.

An MCP proxy that checks tool calls against a pentest scope manifest before forwarding them to your MCP tools. It blocks calls it can identify as outside the targets, techniques, or time window you approved, and records decisions in a local audit log.

Requires Node.js 22 or newer. The proxy supports stdio tools, SSE upstreams such as Burp Suite, and HTTP upstreams.

Managing several tools? The managed gateway adds a browser UI with local MCP server presets, scope templates and technique checkboxes, JSON policy import and download, administrator approval and assignment, and a separate engagement choice for each user. It exposes scoped tools, an active engagement resource, PlexTrac reference resources, a TurboPentest knowledge-base catalog with search and controlled live reads, and guided pentest prompts. It supports one hosted MCP URL for ChatGPT and Claude and a local Burp route.

The MCP workbench shows your live tool calls and background jobs. Intercept requests, edit arguments before forwarding, or drop a call. Long calls return a job ID that you can inspect or cancel without waiting for one MCP request to stay open. The gateway checks scope again after any edit.

To keep the local gateway running after sign-in, use pentest-gateway service install; use pentest-gateway service remove to undo it. It binds to loopback only. See the local startup guide. The gateway cannot prevent an agent with a separate shell or network path from bypassing MCP checks; see the secure deployment guide.

Quick start: add an MCP tool

1. Install the proxy:

   npm install -g @integsec/agentic-pentest-proxy
   

2. Create a scope manifest with the guided wizard:

   pentest-manifest new -o scope.json
   

   Set the real engagement targets and time window. Review the generated file with the engagement owner before using it.

3. Generate a client entry for each MCP tool. Put the tool's normal launch command after --:

   pentest-setup --name scanner-scoped --manifest ./scope.json -- npx -y @example/scanner-mcp
   

   Replace npx -y @example/scanner-mcp with the command from your tool's own setup instructions. The command prints an mcpServers entry. Paste that entry into your MCP client's configuration and restart the client. To add another tool, run setup again with a new --name, then add its entry under the same mcpServers object.

   For example, the generated entry has this shape (the setup command fills in your actual manifest and audit paths):

   {
     "mcpServers": {
       "scanner-scoped": {
         "command": "pentest-proxy",
         "env": {
           "SCOPE_MANIFEST_PATH": "/path/to/scope.json",
           "MCP_TRANSPORT": "stdio",
           "AUDIT_LOG_PATH": "/path/to/audit",
           "UPSTREAM_MCP_COMMAND": "npx",
           "UPSTREAM_MCP_ARGS_JSON": "[\"-y\",\"@example/scanner-mcp\"]"
         }
       }
     }
   }
   

   Use the mcpServers block in Claude Desktop's MCP configuration or in your Claude Code project's .mcp.json. Other MCP clients may label the server settings differently; use the generated command and environment variables in their equivalent fields. The proxy starts when the client launches the tool.

4. Watch decisions in another terminal:

   pentest-tui --audit-path ./audit
   

   Setup prints the exact audit path to use. If your shell is in another directory, use that printed path. For a one-off TUI without a global install:

   npm exec --yes --package=@integsec/agentic-pentest-proxy -- pentest-tui --audit-path ./audit
   

   The TUI reads local audit files; it does not start the proxy. See TUI screenshots.

   

Other MCP tool types

Use one generated client entry per upstream tool. A single scope manifest can be shared by several entries; each call still gets checked. More client examples.

What gets checked

The proxy checks MCP tools/call arguments it can inspect. It blocks unknown target-bearing arguments, out-of-scope targets, explicit exclusions, restricted techniques, expired engagement windows, and free-form commands by default. DNS names authorized through IP ranges must resolve entirely inside the allowed ranges. Local JSONL auditing is always on; cloud logging is optional.

The proxy cannot control destinations selected inside an upstream tool, HTTP redirects, targets read from files or encoded payloads, DNS changes after validation, or traffic that bypasses MCP. Use network egress controls and review each upstream tool's schema before relying on the proxy for an engagement. Security model.

Install and release options

The npm package includes the gateway, proxy, manifest builder, setup helper, TUI, bridge, and scanner adapter. Run pentest-gateway version or pentest-gateway --version to check the installed release. The older integsec- command names still work for existing client configurations. To see the optional install welcome banner, add --foreground-scripts; npm hides package install-script output by default. You can always run pentest-gateway --help for the same next steps. The welcome script does not access the network or modify files.

Google Cloud logging and Secret Manager SDKs are opt-in to keep the default install lean and free of their deprecated transitive package. If you use either GCP backend, install the SDKs alongside the proxy:

npm install -g @integsec/agentic-pentest-proxy @google-cloud/logging @google-cloud/secret-manager

AWS and Azure SDKs are included as optional dependencies. See configuration and cloud setup for the required environment variables and Docker notes. If you use GCP and are upgrading from 0.2.6, install the GCP SDKs before restarting the proxy; it now reports a missing Cloud Logging SDK at startup.

Troubleshooting

Reference

• Configuration and manifest fields
• Client integrations, HTTP, and Docker
• TUI usage and screenshots
• Security model and limitations
• Contributing and development

License

Apache-2.0. See LICENSE.