Labs · mcp-pordego · summary on jarvisosorio.com

mcp-pordego documentation

mcp-pordego (pordego is Esperanto for gate) is an open-source security scanner for the Model Context Protocol (MCP) servers your agents already use. It is a scanner, not an MCP server. It audits MCP setups in Claude Desktop, Claude Code, Cursor and VS Code.

Current version: 0.1.1. License: Apache-2.0. Source: github.com/JarvisOsorio/mcp-pordego.

v0.1 ships the scanner. A policy gateway, lockfile, redaction proxy, audit log and replay are designed in SPEC.md, and the CLI stubs those commands so the surface stays stable, but they are not included in this release.

View the GitHub repository Short project page

What it is for

Developers and security-minded teams who already run MCP servers in Claude, Cursor or VS Code and want a local audit of those configs: unpinned packages, inline secrets, prompt-injection in tool descriptions, over-broad filesystem roots, and related issues.

Install

Requires Node.js 20+ and pnpm. The package is not on the npm registry — do not run npx mcp-pordego. Install from the repository or a GitHub Release asset.

git clone https://github.com/JarvisOsorio/mcp-pordego.git
cd mcp-pordego
pnpm install && pnpm build
pnpm scan -- --help

After the build, the CLI is also at node packages/cli/dist/index.js, or the bundled dist/mcp-pordego.cjs from pnpm bundle.

Or download the v0.1.1 release asset:

curl -L -o mcp-pordego.cjs \
  https://github.com/JarvisOsorio/mcp-pordego/releases/download/v0.1.1/mcp-pordego.cjs
node mcp-pordego.cjs scan --help

Usage

pnpm scan
# or with an explicit config:
node packages/cli/dist/index.js scan --config ./fixtures/configs/bad-mcp.json

pnpm scan auto-discovers MCP configs from:

Client	Paths
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), `%APPDATA%/Claude/…` (Windows), `~/.config/Claude/…` (Linux)
Claude Code	`.mcp.json`, `~/.claude.json`
Cursor	`.cursor/mcp.json`, `~/.cursor/mcp.json`
VS Code	`.vscode/mcp.json`

The scanner exits 1 on high-severity findings (CI-friendly) and 2 on config or integrity errors.

Point at a file or command

node dist/mcp-pordego.cjs scan --config ./fixtures/configs/bad-mcp.json
node dist/mcp-pordego.cjs scan --server "npx -y @modelcontextprotocol/[email protected] /tmp"
node dist/mcp-pordego.cjs scan --live --config .mcp.json

Live mode spawns servers and calls initialize plus tools/list only — never tools/call.

Output formats

node dist/mcp-pordego.cjs scan --format text          # default, colored, grouped by server
node dist/mcp-pordego.cjs scan --format json
node dist/mcp-pordego.cjs scan --format sarif         # GitHub code scanning
node dist/mcp-pordego.cjs scan --fail-on medium       # high | medium | low (default: high)
node dist/mcp-pordego.cjs scan --baseline accepted.json

What it checks

Static (config only)

Rule	Severity	Check
`unpinned-npx`	high	`npx` package without an exact version, or `@latest`
`unpinned-uvx`	high	`uvx` / `pipx run` without `==version`
`unpinned-docker`	high	image with `:latest` or no tag / digest
`unpinned-git`	high	git URL without a commit SHA
`inline-secret`	high	secret-looking value in `env` / `args` / `headers`
`remote-http-no-tls`	high	`http://` to a non-loopback host
`broad-fs-root`	medium	filesystem server rooted at `/`, `~`, or home
`shell-server`	medium	name or package suggests shell or exec capability

Live (`--live`)

Rule	Severity
`desc-injection-phrases`	high
`desc-hidden-chars`	high
`desc-exfil-url`	high
`schema-freeform-exec`	high
`desc-markup-hidden`	medium
`desc-cross-tool-ref`	medium
`schema-freeform-path`	medium
`schema-freeform-url`	medium
`tool-name-collision`	medium
`no-readonly-hint`	low
`desc-oversized`	low

Detection is heuristic. Rules are plain TypeScript modules. The repository includes 42 tests covering static rules, live rules, detectors, discovery and the scan runner (pnpm test).

Roadmap (gateway, not in this release)

Policy-as-code — allow or deny per server and tool, with argument constraints and rate limits
Audit log — hash-chained JSONL of every call
Redaction — strip API keys and tokens from responses
Tool pinning — an mcp-pordego.lock file that blocks silent description changes
Replay — mock or verify recorded sessions

Decisions locked for the v1 gateway: tool pinning on, deny sampling and elicitation by default, and denials returned as MCP results with isError: true (not JSON-RPC errors).

Limitations

Not a sandbox. It inspects configs and tool metadata. It does not isolate upstream server processes.
Heuristics miss things. Encoded injection, novel secret formats and clever shadowing can slip through.
Live mode still trusts the server binary. It only reads tools/list.

See also SECURITY.md and the Labs changelog.