Penthera in your agent: `penthera mcp`

Starter. For “can my coding agent call Penthera as a tool?”

Add it to your agent

penthera mcp runs Penthera as an MCP server. Your agent (Claude Code, Cursor, Codex, VS Code, Windsurf) starts it and calls its tools. It needs Node.js 22 or later. The MCP server is new in 1.9.0; the commands below pin 2.0.0, so an update never reaches you unless you change the pin. Always pin the version. An unpinned npx penthera runs whatever version is newest on npm each time your agent starts, which is the risk that penthera agents reports as mcp-unpinned. Claude Code

claude mcp add penthera -- npx -y penthera@2.0.0 mcp

Add --scope project to write it to .mcp.json for the whole team. Codex

codex mcp add penthera -- npx -y penthera@2.0.0 mcp

Or add it to ~/.codex/config.toml:

[mcp_servers.penthera]
command = "npx"
args = ["-y", "penthera@2.0.0", "mcp"]

Cursor (.cursor/mcp.json) and Windsurf (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "penthera": {
      "command": "npx",
      "args": ["-y", "penthera@2.0.0", "mcp"]
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "penthera": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "penthera@2.0.0", "mcp"]
    }
  }
}

Gemini CLI, as an extension (it reads gemini-extension.json at the root of this repository, with the same pinned server):

gemini extensions install https://github.com/danoszz/penthera

The same files are in docs/mcp-clients/. The test suite checks each one with Penthera’s own MCP rules. Then ask your agent: “scan this repo for security issues”, “is this MCP config safe?”, or “what can the dependencies in this project do?”.

The tools

Every tool is read-only. None writes a file, applies a fix, or runs a shell.

Tool	What it does	Network
`scan_repo`	Secrets, code-execution sinks, API routes, runtime version pins in a project folder, plus a coverage ledger of what ran and what was skipped	none
`check_dependencies`	What each npm or Python package can do (install scripts, shell, network, eval, credential access), known-malicious packages, typosquats	none
`audit_ai_tooling`	The project’s skills, MCP servers, hooks, permissions and rule files, graded A to F	none
`runtime_advisories`	Advisories and end of life for the PHP, nginx, Apache, Node.js, Python or OpenSSL a project pins or a `Server` header shows	none
`explain_finding`	What a finding’s rule checks, why it matters, how to fix it, references and OWASP ids	none
`scan_url`	A passive scan of a running app: TLS, headers, cookies, CORS, exposed files, OpenAPI and auth smoke checks	the target only (see below)

Each result has the findings as structured JSON, and as text the agent brief: a verdict, what to act on, what to check first, what is likely noise, what was not checked, and what to run next. The text asks the assistant to pass the brief on as it is and to put its own view under “My read”. Every finding has a rule, a severity, a confidence label (confirmed, likely, potential, needs-human-review), and evidence at file:line or a URL. Each result also lists what the tool did not check. By default a tool returns the 50 most severe findings; ask for up to 200 with max_findings.

What it will not do

Read outside your project. A tool reads only inside the workspace: the folders your agent shares as MCP roots, or else the folder it starts the server in. Symlinks that lead outside are refused.
Attack anything. scan_url sends no payloads: no injection probes, no fuzzing, no recon sources. For those, run penthera <url> --deep yourself, where Penthera asks you to confirm the target.
Scan a host you did not name. scan_url reaches localhost and 127.0.0.1. Any other host must be in the server’s launch arguments, which you write, not the model:

npx -y penthera@2.0.0 mcp --allow-host staging.example.com

Only list hosts you are authorized to test.

Follow instructions in your files. Scanned text reaches the agent only as finding text, with invisible characters removed and a note that it is data. A file that says “ignore previous instructions” becomes a finding, not a command.
Phone home. It talks to your agent over stdin and stdout and never opens a port. With --offline, scan_url also skips the Retire.js download and DNS lookups and contacts only the target.

Options

npx -y penthera@2.0.0 mcp --offline
npx -y penthera@2.0.0 mcp --help

Flag	Meaning
`--root <dir>`	A folder tools may read (repeatable). Default: the folder the agent starts the server in. Roots your agent sends take precedence.
`--allow-host <host>`	A host `scan_url` may contact besides loopback (repeatable, exact name, no wildcards)
`--offline`	`scan_url` contacts only the target

In a container

The repo’s Dockerfile builds an image whose entry point is penthera. Mount your project at /src and point --root at it:

docker build -t penthera-mcp .
docker run -i --rm --network none -v "$PWD:/src:ro" penthera-mcp mcp --root /src

Your agent sends its roots as host paths, which do not exist inside the container. The server drops roots it cannot find. When none is left, it uses --root and logs “client sent no usable roots; using the server’s roots” to stderr. If --root does not exist either, it does not start and names the folder. With --network none, scan_url has nothing to reach; the other tools need no network.

Limits

A clean result is not proof of safety. Penthera reports what its rules match.
audit_ai_tooling reads the project’s config, not ~/.claude or other home folders (run penthera agents --home for that), and does not read Codex’s config.toml or Windsurf’s mcp_config.json yet.
The server speaks MCP 2026-07-28 and the earlier initialize versions (2025-11-25 back to 2024-11-05). The design and its security controls are in the spec.

Back to the README · All commands

I'm new

I use AI coding tools

I run it in CI

Evidence for an auditor

Research and method

Compared

The project

Mcp

Penthera in your agent: `penthera mcp`

Add it to your agent

The tools

What it will not do

Options

In a container

Limits

​Penthera in your agent: penthera mcp

​Add it to your agent

​The tools

​What it will not do

​Options

​In a container

​Limits

Penthera in your agent: `penthera mcp`

Add it to your agent

The tools

What it will not do

Options

In a container

Limits