Skip to main content

🔌 mcpaudit

Security scanner for MCP server tool surfaces.

CI PyPI 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

Measured results

From a hand-labelled scan of public MCP servers (mcp-scan-study):

  • Scope-rule precision: the v0.7 rewrite raised strict precision of HIGH permission_scope findings from 40% to 72.7% on a blind-labelled fresh corpus of 45 repositories, keeping all 16 accurate findings.
  • Obfuscation: description rules match a normalised form of the text, so look-alike letters, letter-spacing, doubled spaces and zero-width characters no longer evade them; findings on 7,991 real tool descriptions were unchanged by that hardening.
  • In the wild: no genuine tool poisoning was found across 135 public repositories. Most HIGH scope findings are by-design capabilities, which is why findings are review input, not verdicts.

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]"

How a scan flows

flowchart LR
    T["MCP server<br/>(stdio or Streamable HTTP)"] --> C["MCPClient<br/>fetch tool manifest"]
    C --> M["ServerManifest"]
    M --> D["description_scan<br/>(normalised text rules)"]
    M --> P["permission_scope"]
    M -. "--dynamic" .-> X["confused_deputy<br/>(target model via adapter)"]
    D --> A["findings"]
    P --> A
    X --> A
    A --> Y["Policy.apply<br/>(--policy suppression)"]
    Y --> R["report<br/>text / JSON / SARIF"]
    R --> G{"--fail-on<br/>threshold"}
    G -->|"at or above"| E1["exit 1"]
    G -->|"below"| E0["exit 0"]
    M -. "baseline / diff" .-> RP["rug_pull<br/>manifest diff"]

Quick start

Demo

terminal demo: mcpaudit scan against samples/malicious_server

Real output of mcpaudit scan -- python samples/malicious_server/server.py (ANSI stripped; per-finding explanation paragraphs omitted for width).

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
├── normalize.py           # canonical text for rules (look-alikes, spacing, invisible characters)
├── 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.9.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.9.0
File Size Uploaded Provenance Actions
pyhroff_mcpaudit-0.9.0.tar.gz 39.6 kB With provenance Details for pyhroff_mcpaudit-0.9.0.tar.gz

Built distribution (wheel)

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

Total release size: 71.0 kB

Release files / pyhroff_mcpaudit-0.9.0.tar.gz

Download URL pyhroff_mcpaudit-0.9.0.tar.gz
Size 39.6 kB
Tags Source
SHA-256 checksum
How to use checksums
9569030934ae70f1f0aa0a98f3aecfb6b596c50587a560febcaa136b46dac67f
BLAKE2b-256 checksum
How to use checksums
9c98f0dd70fa78dd2f67fe757245998f8ff4d3cbce11e7fd419e09b95a94e18e
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 Nov 18, 2026.

Transparency log

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

Download URL pyhroff_mcpaudit-0.9.0-py3-none-any.whl
Size 31.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
13a1cd25c75d061ba4f16f741f3bc26daef2bf75d2964c5b44755ff90b724dbb
BLAKE2b-256 checksum
How to use checksums
5e1b26d49cdd3660708178947e4892a4f711f54059ac04e5995ca1fe1b1d0020
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 Nov 18, 2026.

Transparency log

Security for pyhroff-mcpaudit 0.9.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.9.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 Nov 18, 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