Security and quality
A scanner you run on your own machine has to earn that access. This page says what mcp-audit does and does not do, how it is tested and released, and what we have measured, with a link to the evidence for each claim.
To report a security issue in mcp-audit itself, follow the security policy.
At a glance
- Offline by designscan and check make no network calls unless you add a network flag. fix, sbom and lock look up package versions online by default; --offline stops that.
- Reads, never runsScanned files are parsed, never executed: no servers started, no scripts, no git.
- No telemetryNo usage data, no crash reports and no account to create.
- Signed advisory feedOSV 1.6.0 records signed with the project's minisign key, published weekly.
- Attested releasesPyPI Trusted Publishing with PEP 740 attestations, and a CycloneDX SBOM for every binary.
- 10,382 automated testsThe suite runs on Linux, macOS and Windows with Python 3.11 and 3.12 on every push and pull request.
- OWASP MCP Top 10Findings map to 10 of 10 categories, and CI checks the mapping on every change.
- Measured in publicPoisoning recall is 75% on a public benchmark and none of 46 findings on the top-100 npm servers was real. GAPS.md lists what we miss.
What a default scan does
It finds MCP configs, Claude Code settings, installed plugins, skills and subagents, and the git settings and CI workflows of the folder you run it in (and the injection checks on agent instruction files when you add --include-agent-files), reads them, and reports what it found. It does not start servers, run scripts or call git. It collects no telemetry and makes no network calls. It keeps a hash of each server's config entry in your user config folder, so the next scan can tell what changed.
These scan flags use the network, and you add each one yourself:
--connectstarts or connects to each configured server and reads its live tool list.--check-vulnslooks up dependency advisories at deps.dev and OSV.dev.--verify-hashesdownloads package tarballs to check their hashes.--verify-signaturesfetches Sigstore provenance from npm and PyPI.vet --onlinefetches the verdict from this site;lock --resolveasks the package registry what a version range resolves to;update-registrydownloads the latest registry from GitHub.
The commands fix, sbom and lock also look up package versions online by default. They send package names and versions, never your config, and --offline on each of them stops it. --offline on scan refuses every network flag. One more thing is opt-in: if you run mcp-audit register, later check runs send your mcp-audit version and grade. Registration never sends anything about your configs.
Evidence: docs/telemetry.md, docs/privacy.md, src/mcp_audit/_network.py
Tests and CI
mcp-audit has 10,382 automated tests. The suite runs on Linux, macOS and Windows with Python 3.11 and 3.12 on every push and pull request, in a workflow that also runs:
- Lint and format checks.
- A run with every optional extra installed.
- A check that every finding ID has an OWASP mapping.
- A check that the counts in the README match the code.
- A check that the built wheel's metadata is accepted by PyPI tooling.
GitHub CodeQL also analyses the code on pull requests and weekly.
6 test classes in tests/test_exploit_validation.py rebuild published attack proofs of concept and assert the exact finding IDs and severities they produce.
Evidence: .github/workflows/ci.yml, scripts/update_test_count.py
Releases you can verify
Releases are published to PyPI from GitHub Actions with Trusted Publishing, so publishing needs no stored PyPI token; each upload carries PEP 740 attestations that tie it to the workflow that built it. Standalone binaries are built for macOS (Apple silicon), macOS (Intel), Linux (x86-64) and Windows (x86-64), and each one ships with a CycloneDX SBOM. A release gate checks that the tag, the version in pyproject.toml and a non-empty changelog section all agree before anything is published.
Evidence: .github/workflows/release.yml, docs/building-binaries.md
A signed advisory feed
OSV and NVD track vulnerable packages, but no feed tracks MCP-specific findings, so mcp-audit publishes one. mcp-audit advise turns findings into OSV 1.6.0 records, canonicalized with RFC 8785 so the same finding produces the same bytes on any machine. A weekly build signs the feed with the project's minisign key, and mcp-audit feed verify checks every record against the signed index offline. A separate daily check fails loudly if the published feed gets close to expiry.
Published feed: https://raw.githubusercontent.com/adudley78/mcp-audit/feed/index.json
Project public key B80A5199FE49D0E1:
RWTh0En+mVEKuP0KTB1CfAp1xQsJ3X2yplfbWzXZnHx9MRyuZ/z0Otz5Evidence: docs/advisory-feed.md, keys/mcp-audit-feed.pub
Mapped to the OWASP MCP Top 10
219 of the 225 finding IDs carry OWASP MCP Top 10 codes; the other 6 record bookkeeping or errors, not a risk. Together the checks cover 10 of the 10 categories. CI fails a pull request that adds a finding ID without a mapping. SARIF output includes the taxonomy, so the codes show up in GitHub code scanning.
MCP01Token Mismanagement and Secret Exposure 38 checksMCP02Privilege Escalation via Scope Creep 31 checksMCP03Tool Poisoning 44 checksMCP04Software Supply Chain Attacks 62 checksMCP05Command Injection and Execution 45 checksMCP06Intent Flow Subversion 28 checksMCP07Insufficient Authentication and Authorization 25 checksMCP08Lack of Audit and Telemetry 4 checksMCP09Shadow MCP Servers 24 checksMCP10Context Injection and Over-sharing 21 checks
See which checks map to each category
Evidence: docs/owasp-mapping.json, scripts/validate_owasp_mapping.py
Detection quality, measured
We measured how often the poisoning checks (POISON-*) are right and published the method, the labels and the results, dated 2026-10-25. Recall is the share of poisoned tool descriptions flagged. Precision is the share of findings that were real attacks. The left-hand figures count a finding of any severity, which is what a plain scan exits 1 on. The right-hand figures count HIGH or above, which is what check and the pre-commit hook fail on.
| Measure | Corpus | Any severity | HIGH or above |
|---|---|---|---|
| Recall: poisoned descriptions flagged | MCPTox, 1,312 cases | 74.7% (980 of 1,312) | 69.3% (909 of 1,312) |
| Recall: cases that carry an <IMPORTANT> block or an “Ignore the previous instructions” line | MCPTox, 877 of those cases | 877 of 877 | 877 of 877 |
| Recall: descriptions with no wrapper | MCPTox pure_tool.json, 485 descriptions | 25.4% (123 of 485) | 7.2% (35 of 485) |
| Real tools flagged | MCPTox, 353 clean tools from 45 servers | 2 (0.6%) | 0 (0.0%) |
| Precision: findings that were real attacks | Live tools of the top-100 npm servers: 46 findings on 1,402 tools (mcp-audit 0.23.0) | 1 of 46 | 0 of 2 |
The checks catch poisoning that announces itself. Without that wrapper they flag about one description in four, and about one in 14 at the HIGH threshold. Parameter tampering is the weakest case: 6.7% of the descriptions that change another tool's arguments. On the servers people install, the checks are noisy. None of the 46 findings on the top-100 npm servers was an attack. The precision row is a fixed measurement of mcp-audit 0.23.0, since repeating it means running those servers again.
The cross-tool delegation checks (DELEG-001 to DELEG-003, which run with --connect) were measured before they shipped. On the same 485 descriptions they flag 98.4% when the poisoned tool comes from its own server, the benchmark's threat model, and 2.7% when it is listed among the target server's own tools. They flagged 1 of 353 clean tools. The POISON-* checks flag 25.4% of the same descriptions.
These numbers describe the datasets named in the table, not your configs. The benchmark script is development tooling, and a test fails CI when the poisoning code changes without a re-measurement.
Evidence: docs/poisoning.md, docs/research/poisoning-benchmark/results.json, scripts/bench_poisoning.py
Measured in public
On 2026-10-22, we scanned the 100 most-downloaded MCP servers on npm with mcp-audit and published the corpus, the scripts and every aggregate number.
- 60 of the 100 servers completed a live connection; together they exposed 1,611 tools.
- mcp-audit's poisoning rules raised 661 findings, and none of them was a real attack; 488 came from one rule, POISON-060.
- Dependency lookups found 92 distinct advisories across 27 servers' dependency trees; mcp-audit does not check whether the vulnerable code is reachable.
The scan also measured mcp-audit. The published write-up lists these defects in mcp-audit itself:
- POISON-060 (Unicode homoglyph substitution) fires on full-width punctuation in tool descriptions written in Chinese.
- SC-004 compares versions numerically and reads
@modelcontextprotocol/server-filesystem2.0.0 as older than 2025.7.1 after the package moved from calendar versions to semver, so it reports two fixed CVEs as present. - COMM-010 ("npx without a pinned version") fires on every server in the config, all of which are pinned, because it checks the command and not the arguments.
- SC-003 reports
@netlify/mcpas a lookalike of@mintlify/mcp. --check-vulnsreports every dependency advisory as INFO with no summary, HIGH advisories included.
Evidence: docs/research/2026-10-top100-npm/
Where the detection logic comes from
Every pattern is written for mcp-audit from published research; no code is copied from other scanners. Each finding's source is cited: vendor research, CVEs, academic measurements and framework guidance, listed per rule.
Evidence: PROVENANCE.md, docs/severity-framework.md
What it does not catch
A scanner is only as useful as its known limits. We keep them in one public file, including detections we measured and chose not to ship. A few that matter most:
- A static scan sees what a config says. What a remote server actually serves is only visible with
--connect, which starts the servers. - Regex-based poisoning detection can be evaded and can misfire; the measurement above shows where it misfired.
- Dependency advisories are reported without reachability analysis.
- Some agent surfaces (for example Windsurf, Augment and Kiro instruction files) are not read yet.
Evidence: GAPS.md
A curated registry
The registry behind vet and the server pages lists 56 packages, added by review rather than crawling. A package is marked verified only with evidence that the submitter controls it; 26 are verified today. A weekly job checks OSV for new advisories on every listed package.
Evidence: registry/known-servers.json, docs/registry-contributions.md