Included Tools

• nmapScan
• runJohnTheRipper
• runHashcat
• gobuster
• nikto
• subfinderEnum
• httpxProbe
• ffufScan
• nucleiScan
• trafficCapture
• hydraBruteforce
• privEscAudit
• extractionSweep
• generateWordlist
• listEngagementRecords
• getEngagementRecord
• createClientReport
• cancelScan

Quick Start

Install

npm install -g pentest-mcp

Run locally (stdio)

pentest-mcp

Launch bundled MCP Inspector (no separate install)

pentest-mcp inspector

You can forward Inspector flags directly:

pentest-mcp inspector --help

Run over network (Streamable HTTP)

MCP_TRANSPORT=http MCP_SERVER_HOST=0.0.0.0 MCP_SERVER_PORT=8000 pentest-mcp

Run legacy SSE mode (deprecated)

MCP_TRANSPORT=sse MCP_SERVER_PORT=8001 pentest-mcp

Transport Notes

• stdio: default for local MCP clients.
• http: modern network transport. Recommended.
• sse: compatibility only. Deprecated and will be removed in a future major release.

Inspector Integration

• pentest-mcp inspector launches the bundled @modelcontextprotocol/inspector CLI.
• It auto-targets this MCP server over stdio by spawning:
  • node <this-package-entrypoint> stdio
• You do not need to install Inspector separately.

Auth Configuration (Bearer + OIDC)

Set these env vars when using MCP_TRANSPORT=http (or sse if needed):

MCP_AUTH_ENABLED=true
MCP_AUTH_MODE=bearer
MCP_AUTH_SCOPES=read,write
MCP_AUTH_AUDIENCE=
MCP_OIDC_ISSUER=https://issuer.example.com
MCP_OIDC_JWKS_URL=https://issuer.example.com/.well-known/jwks.json
# optional alternative/backup validation mode:
MCP_OIDC_INTROSPECTION_URL=https://issuer.example.com/oauth/introspect
MCP_OAUTH_CLIENT_ID=...
MCP_OAUTH_CLIENT_SECRET=...

Legacy aliases are still accepted temporarily:

• MCP_OAUTH_ENABLED
• MCP_OAUTH_PROVIDER_URL
• MCP_OAUTH_SCOPES

Workflow + Reporting

createClientReport now supports SoW handling modes:

• scopeMode=ask: prompt user via MCP elicitation (recommended)
• scopeMode=provided: use scopeOfWork value directly
• scopeMode=template: use built-in generic authorized-testing template

If elicitation is declined/unavailable, the report automatically falls back to the template.

How users provide SoW (right now)

There is no separate file-upload API yet. Current options are:

1. Ask interactively via MCP user invocation (elicitation)

{
  "tool": "createClientReport",
  "arguments": {
    "title": "Q1 External Pentest",
    "assessmentType": "external-network",
    "scopeMode": "ask"
  }
}

2. Paste SoW text directly into scopeOfWork

{
  "tool": "createClientReport",
  "arguments": {
    "title": "Q1 External Pentest",
    "assessmentType": "external-network",
    "scopeMode": "provided",
    "scopeOfWork": "Authorized targets: ...\nOut-of-scope: ...\nTesting window: ...\nRules of engagement: ..."
  }
}

3. Use template mode when client details should not be shared

{
  "tool": "createClientReport",
  "arguments": {
    "title": "Q1 External Pentest",
    "assessmentType": "external-network",
    "scopeMode": "template"
  }
}

How this cuts admin time

• Every tool run stores a structured engagement record (recordId=...) with invocation context.
• Use listEngagementRecords to pull all work artifacts quickly.
• Generate the report from selected recordIds (or latest records by default) instead of manual copy/paste.
• Scope notes are attached automatically from one of:
  • user elicitation form (ask)
  • pasted SoW text (provided)
  • safe default template (template)

Roadmap

These are planned specifically to reduce pentest admin overhead.

• scopeFilePath ingestion (load SoW from a local file path on the MCP host)
• scopeDocument chunked upload flow (send SoW content directly through MCP for remote clients)
• SoW parser that auto-extracts targets, exclusions, test windows, and rules of engagement
• Evidence auto-linking from tool outputs (recordId) to findings and report sections
• Finding dedup/merge across overlapping tools (nuclei, nikto, etc.)
• Auto severity + impact draft text for faster writeups
• One-click report pack generation (executive summary + technical appendix + remediation table)
• Retest diff mode (fixed/reopened/new findings between engagements)
• Ticket export sync (Jira/Linear/GitHub) with status backfill
• Deliverable QA checks (missing evidence, missing scope fields, weak remediation notes)

Adoption note:

• Expect strong usage for scopeFilePath and scopeDocument because most teams already maintain SoW in docs/PDF and want to avoid repeated paste-and-reformat steps.

Recon + Exploitation Examples

Subdomain enumeration

{
  "tool": "subfinderEnum",
  "arguments": {
    "domain": "example.com",
    "recursive": true,
    "allSources": true
  }
}

Probe live hosts

{
  "tool": "httpxProbe",
  "arguments": {
    "targets": ["example.com", "api.example.com"],
    "includeTitle": true,
    "includeStatusCode": true
  }
}

Fuzz content paths

{
  "tool": "ffufScan",
  "arguments": {
    "targetUrl": "https://example.com/FUZZ",
    "wordlist": "/usr/share/seclists/Discovery/Web-Content/common.txt",
    "threads": 40
  }
}

Template scanning

{
  "tool": "nucleiScan",
  "arguments": {
    "targets": ["https://example.com"],
    "severities": ["medium", "high", "critical"]
  }
}

Traffic capture (sniffing)

{
  "tool": "trafficCapture",
  "arguments": {
    "networkInterface": "eth0",
    "packetCount": 200,
    "bpfFilter": "tcp port 80"
  }
}

Brute-force checks

{
  "tool": "hydraBruteforce",
  "arguments": {
    "target": "10.10.10.20",
    "service": "ssh",
    "usernameList": "/usr/share/seclists/Usernames/top-usernames-shortlist.txt",
    "passwordList": "/usr/share/seclists/Passwords/Common-Credentials/10k-most-common.txt"
  }
}

SQLi extraction sweep

{
  "tool": "extractionSweep",
  "arguments": {
    "targetUrl": "https://target.local/item.php?id=1",
    "risk": 2,
    "level": 3
  }
}

Docker

docker-compose --profile http up
docker-compose --profile stdio up
docker-compose --profile sse up

The Docker image installs:

• nmap, john, hashcat, gobuster, nikto, ffuf, hydra, sqlmap, tcpdump
• subfinder, httpx + httpx-toolkit alias, nuclei

Required Host Tools (non-Docker runs)

Ensure the binaries are in PATH:

which nmap john hashcat gobuster nikto subfinder httpx-toolkit ffuf nuclei hydra sqlmap tcpdump

If httpx-toolkit is not installed, a validated ProjectDiscovery httpx binary is accepted as fallback.

Security Notice

Authorized use only. Run against systems/networks where you have explicit written permission.

Appendix: MCP in Practice (Code Execution, Tool Scale, and Safety)

Last updated: 2026-03-23

Why This Appendix Exists

Model Context Protocol (MCP) is still one of the most useful interoperability layers for tools and agents. The tradeoff is that large MCP servers can expose many tools, and naive tool-calling can flood context windows with schemas, tool chatter, and irrelevant call traces.

In practice, "more tools" is not always "better outcomes." Tool surface area must be paired with execution patterns that keep token use bounded and behavior predictable.

The Shift to Code Execution / Code Mode

Recent workflows increasingly move complex orchestration out of chat context and into code execution loops. This reduces repetitive schema tokens and makes tool usage auditable and testable.

Core reading:

• Cloudflare: Code Mode
• Cloudflare: Code Execution with MCP
• Anthropic: Code Execution with MCP

Recommended Setup for Power Users

For users who want reproducible and lower-noise MCP usage, start with a codemode-oriented setup:

• codemode-mcp (jx-codes)
• UTCP

Practical caveat: even with strong setup, model behavior can still be inconsistent across providers and versions. Keep retries, guardrails, and deterministic fallbacks in place.

Peter Steinberger-Style Wrapper Workflow

A high-leverage pattern is wrapping MCP servers into callable code interfaces