🔌 mcpaudit
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_scopefindings 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
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:
- Run static checks on every change.
- Fail CI for findings at or above your chosen severity.
- Keep an approved manifest for production tool surfaces.
- Run
mcpaudit diffwhen the server's tool surface changes. - 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.