Overview

Pentest MCP is a TypeScript MCP server for authorized security assessments. It gives a human researcher or a tool-using assessment agent one scoped interface for discovery, validation, capture, credential checks, local audit, evidence retrieval, and report preparation. Each active tool call is tied to an engagement and a durable record. The server checks the declared targets and time window; the researcher verifies findings before publication.

October 2026 workflow

1. Create an engagement from signed authorization and rules of engagement, then save the assessment plan. The operator chooses a stable engagementId.
2. A researcher or fresh Codex process in the managed assessment container connects to the Pentest MCP server. It sees the complete catalog, while the plan's exact allowedToolNames list permits only selected calls. Active tools also pass the engagement target and time gate.
3. Review recordId values and correlated scope decisions with listEngagementRecords and getEngagementRecord. Records persist across restarts. Import external research with recordResearchActivity; the import does not replace MCP tool use.
4. Draft a report from the complete evidence ledger, inspect candidate findings against source records, and publish only analyst-verified findings. Retrieve Markdown or JSON later with getClientReport.

The declared-target check is an operational guardrail, not a complete network boundary. DNS changes, redirects, Nmap scripts, Nuclei templates, and other third-party tool behavior can create secondary traffic. Review tool configuration and keep network controls aligned with the engagement's rules.

Agentic assessment uses the MCP tools

The assessment stage is a tool-using agent session. runAgentAssessment supports local Codex or Claude in a dedicated account profile, Codex in a pinned container, a loopback OpenAI-compatible server such as llama.cpp or Ollama, and OpenRouter. CLI workers receive a locked, single-engagement Pentest MCP server and discover the full catalog. Guarded API models receive only the exact plan allowlist intersected with the worker catalog. Every requested action still reaches the same worker-side plan, target, parent-status, and time checks before a handler starts. Optional hostileModelProtection adds duplicate-action, token-accounting, and finish-reason circuit breakers and defaults to false. An interrupted run with a durable start receipt and no terminal receipt blocks replay; reconcileAgentAssessment requires an operator to confirm that the prior process stopped, records reviewer and rationale, and revokes the prior worker scope when it is still available. The returned toolCounts, importedRecordIds, and importMapRecordId identify recorded actions and imported evidence. A run with no successful assessment-tool call fails.

draftAssessmentReport is a later, context-quarantined report-writing step; a draft alone does not show that Pentest MCP helped the assessment. OpenAI, Anthropic, OpenRouter, OpenAI-compatible, local Codex, local Claude, container Codex, and configured SSH profiles can draft from a bounded evidence packet without scanner tools. local-agent accepts self-hosted CLI profiles and loopback OpenAI-compatible profiles while rejecting hosted providers before context is sent. The guarded model guide gives llama.cpp and OpenRouter profiles, enforced stop conditions, audit fields, and hostile-model deployment boundaries. The container assessment guide gives CLI profile fields, real acceptance command, and isolation limits. The agentic workflow covers scope, evidence review, and Daybreak/Glasswing access.

Release acceptance uses scripts/run-real-acceptance.mjs. It has no default target or authorization and refuses to pass unless installed Nmap and ProjectDiscovery HTTPX create successful evidence records. With --profile, the managed agent must invoke both through Pentest MCP. With --report-profile, a separate report context must produce the saved draft. Test doubles remain in automated tests only and are never shipped as acceptance receipts.