Skip to main content

🔌 mcpaudit

Security scanner for MCP server tool surfaces.

CI Python License


Why mcpaudit?

MCP servers turn tool names, descriptions, schemas, and tool output into model-visible context. That surface can become an attack boundary.

mcpaudit is a focused scanner for that boundary. It inspects MCP tool surfaces for:

  • Tool poisoning — model-directed instructions embedded in tool descriptions.
  • Over-broad scope — filesystem, command, network, or URL parameters that expose excessive authority.
  • Rug pulls — unexpected changes to a previously approved tool manifest.
  • Confused-deputy behavior — whether untrusted tool-returned content can influence model actions during a controlled dynamic experiment.

It is the MCP-focused scanner inside aisec-suite, but can also be used independently.

Status: Beta · Python 3.10+ · version 0.8.0

What it actually scans

MCP server
    │
    ├── tool name
    ├── description
    ├── input schema
    └── tool output (dynamic mode)
          │
          ▼
      mcpaudit
          │
          ├── description_scan
          ├── permission_scope
          ├── rug_pull
          └── confused_deputy
          │
          ▼
   findings / JSON scorecard

The scanner is intentionally surface-oriented: it does not claim that a static finding is proof of exploitation, and it does not execute package installation hooks.

Install

From PyPI:

pip install pyhroff-mcpaudit

For HTTP transport support:

pip install "pyhroff-mcpaudit[http]"

For the optional dynamic model experiment:

pip install "pyhroff-mcpaudit[dynamic]"

For local development:

git clone https://github.com/Pyhroff/mcpaudit.git
cd mcpaudit
pip install -e ".[dev]"

Quick start

Scan a local stdio server

mcpaudit scan -- python samples/malicious_server/server.py

Scan a Streamable HTTP server

mcpaudit scan --url https://example.com/mcp

Produce a machine-readable scorecard

mcpaudit scan \
  --json report.json \
  --sarif report.sarif \
  --fail-on high \
  -- python my_server.py

--sarif generates standard OASIS SARIF v2.1.0 JSON reports compatible with GitHub Advanced Security / Code Scanning. --fail-on makes the scanner useful as a CI gate: the command exits non-zero when a finding meets or exceeds the selected severity.

Track tool-manifest drift

Create a trusted baseline:

mcpaudit baseline -o approved.json -- python my_server.py

Compare a later server state:

mcpaudit diff approved.json -- python my_server.py

This treats unexpected tool-surface changes as reviewable security findings rather than silently accepting them.

Suppress reviewed findings with policy

mcpaudit scan \
  --policy samples/example-policy.json \
  --fail-on high \
  -- python my_server.py

Policy suppression is explicit and happens before rendering, JSON output, and --fail-on evaluation.

Detector matrix

Detector Input Security question
description_scan Tool descriptions Is the model being instructed by attacker-controlled metadata?
permission_scope Tool schemas Does a tool expose unusually broad authority or dangerous parameter shapes?
rug_pull Trusted + current manifests Did the tool surface change after approval?
confused_deputy Live tool + target model Can untrusted tool output influence the model's subsequent behavior?

Static detectors run by default. The confused-deputy experiment is opt-in with --dynamic.

Dynamic confused-deputy experiment

GROQ_API_KEY=... \
mcpaudit scan \
  --dynamic \
  --target groq/openai/gpt-oss-120b \
  -- python my_server.py

You can restrict the experiment to one tool:

GROQ_API_KEY=... \
mcpaudit scan \
  --dynamic \
  --tool suspicious_tool \
  -- python my_server.py

The dynamic path currently uses a Groq target adapter. If the API key is absent, the dynamic check is skipped rather than treating the missing model connection as a scanner finding.

CI usage

A minimal security gate:

mcpaudit scan --fail-on high --json mcpaudit-report.json -- python server.py

Recommended workflow:

  1. Run static checks on every change.
  2. Fail CI for findings at or above your chosen severity.
  3. Keep an approved manifest for production tool surfaces.
  4. Run mcpaudit diff when the server's tool surface changes.
  5. Treat dynamic results as experimental evidence that should be reviewed alongside the static findings.

Umbrella integration

aisec scan .

The umbrella adds repository-level extraction, structural poisoning analysis, and reachability annotations around the static mcpaudit checks.

Use mcpaudit directly when you need live MCP-server scanning, manifest baselines, or the dynamic confused-deputy experiment.

Security model and limitations

mcpaudit is a security analysis tool, not a malware verdict or a complete MCP sandbox.

  • Static analysis can miss runtime behavior and novel attack paths.
  • A flagged pattern may be legitimate application behavior and requires review.
  • A clean scan does not prove that a server is safe.
  • Dynamic experiments are bounded by the selected model, tool, fixture, and prompt.
  • Network and application-specific authorization controls remain outside the scanner's guarantees.

Use it against systems you own or are explicitly authorized to test.

Development

Run the test suite:

pytest -q

The project also participates in the shared agent-test-range regression suite. Cross-repository CI uses pinned shared actions and short-lived GitHub-provided installation credentials rather than a long-lived checkout token.

Project structure

mcpaudit/
├── cli.py                 # Typer CLI and scan/baseline/diff commands
├── manifest.py            # MCP server/tool manifest representation
├── mcp_client.py          # stdio + Streamable HTTP clients
├── findings.py            # normalized finding model
├── report.py              # text/JSON reporting and risk scoring
├── policy.py              # reviewed-finding suppression
├── checks/
│   ├── description_scan.py
│   ├── permission_scope.py
│   ├── rug_pull.py
│   └── confused_deputy.py
└── adapters/
    └── groq.py            # dynamic target adapter

Relationship to the Pyhroff AI-security stack

Project Role
mcpaudit MCP tool-surface scanner
memsentry Memory-injection / persistent-context analysis
ragsentry RAG-oriented security analysis
wormsentry Package-worm / supply-chain behavior detection
adversagen Adversarial evaluation and payload mutation
aisec-suite Umbrella CLI and repository-level integration

The projects are intentionally separated by attack surface so individual scanners can remain focused and composable.

Security research & evaluation

This project documents its security boundary explicitly:

The intended evidence chain is threat → fixture → detector → benchmark → limitation, so scan results are reproducible rather than presented as universal security guarantees.

License

MIT

Metadata

Release files for pyhroff-mcpaudit 0.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyhroff-mcpaudit 0.8.0
File Size Uploaded Provenance Actions
pyhroff_mcpaudit-0.8.0.tar.gz 33.2 kB With provenance Details for pyhroff_mcpaudit-0.8.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pyhroff-mcpaudit 0.8.0
File Interpreter ABI Platform Actions
pyhroff_mcpaudit-0.8.0-py3-none-any.whl Python 3 none any Details for pyhroff_mcpaudit-0.8.0-py3-none-any.whl

Total release size: 60.6 kB

Release files / pyhroff_mcpaudit-0.8.0.tar.gz

Download URL pyhroff_mcpaudit-0.8.0.tar.gz
Size 33.2 kB
Tags Source
SHA-256 checksum
How to use checksums
d6030de778bd50a1c1873f72c0cc86034a834b2dbbdd6571b99fcff282e5d88a
BLAKE2b-256 checksum
How to use checksums
11928b8c0f47911004fdc931376518ce3307384f15c7bc50585c23f25a9878ef
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.

Transparency log

Release files / pyhroff_mcpaudit-0.8.0-py3-none-any.whl

Download URL pyhroff_mcpaudit-0.8.0-py3-none-any.whl
Size 27.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6ae15f0825d2c345367450ddfd389404f6687b1cb313433d34fa5e6f090cb9fa
BLAKE2b-256 checksum
How to use checksums
fac63e108c84c306fa1a3f9290a82f201e93f5c148e9913ab5e82cc61e7eb8e5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.

Transparency log

Security for pyhroff-mcpaudit 0.8.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pyhroff_mcpaudit-0.8.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page