Pentest MCP

Professional penetration-testing MCP server with modern transport/auth support and expanded recon tooling.

What Changed in 0.9.0

• Upgraded MCP SDK to @modelcontextprotocol/sdk@^1.26.0
• Kept MCP Inspector at the latest release (@modelcontextprotocol/inspector@^0.20.0) with bundled launcher
• Streamable HTTP is now the primary network transport (MCP_TRANSPORT=http)
• SSE is still available only as a deprecated compatibility mode
• Added bearer-token auth with OIDC JWKS and introspection support
• Added first-class tools: subfinderEnum, httpxProbe, ffufScan, nucleiScan, trafficCapture, hydraBruteforce, privEscAudit, extractionSweep
• Added report-admin tools: listEngagementRecords, getEngagementRecord
• Added SoW capture flow for reports using MCP elicitation (scopeMode=ask) with safe template fallback
• Hardened command resolution so web probing uses httpx-toolkit (preferred) or validated ProjectDiscovery httpx, avoiding Python httpx CLI collisions
• Integrated bundled MCP Inspector launcher (pentest-mcp inspector)
• Runtime baseline is now Node.js 22.7.5+
• Added invocation metadata in new tool outputs when auth/session context is available

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 and task-focused CLIs instead of exposing every raw tool to the model at all times.

Reference tooling:

• MCPorter
• OpenClaw

Client Fit Guide (Short Version)

• Claude Code / Codex / Cursor: strong for direct MCP workflows, but still benefit from narrow tool surfaces.
• Code execution wrappers (TypeScript/Python CLIs): better when tool count is high or task chains are multi-step.
• Hosted chat clients with weaker MCP controls: often safer via pre-wrapped CLIs or gateway tools.

This space changes fast. If you are reading this now, parts of this guidance may already be stale.

Prompt Injection: Risks, Impact, and Mitigations

Prompt injection remains an open security problem for tool-using agents. It is manageable, but not "solved."

Primary risks:

• Malicious instructions hidden in tool output or remote content.
• Secret exfiltration and unauthorized external calls.
• Unsafe state changes (destructive file/system/API actions).

Consequences:

• Data leakage, account compromise, financial loss, and integrity failures.

Mitigation baseline:

• Least privilege for credentials and tool scopes.
• Allowlist destinations and enforce egress controls.
• Strict input validation and schema enforcement.
• Human confirmation for destructive/high-risk actions.
• Sandboxed execution with resource/time limits.
• Structured logging, audit trails, and replayable runs.
• Output filtering/redaction before model re-ingestion.

Treat every tool output as untrusted input unless explicitly verified.

MCP Compliance State

This server targets MCP protocol version 2025-11-25 and SDK @modelcontextprotocol/sdk@^1.27.1.

Feature	Status
stdio transport	Supported (default)
Streamable HTTP transport	Supported (MCP_TRANSPORT=http)
SSE transport (legacy)	Deprecated compatibility mode
Tool annotations	All tools annotated with title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint
Bearer auth (OIDC/JWKS)	Supported
Origin validation (HTTP)	403 on invalid Origin when MCP_ALLOWED_ORIGINS is set
JSON Schema 2020-12	Zod-generated schemas
Structured tool errors	isError flag with descriptive messages for model self-correction
Elicitation	Used for SoW capture in report generation