MCP Blast-Radius Auditor is used to see the actual reach of any MCP server before adding it to an Agent. The tool supports static blast-radius extraction and can serve as a CI deviation gate for MCP servers. Even if the target server does not declare a manifest, a full blast-radius report can still be obtained; if the server declares a manifest, deviations between its actual behavior and declared boundaries can additionally be captured.
Purpose
- Before onboarding a third-party MCP server, assess its potential impact scope.
- When a server provides a manifest, discover that it touched files it claimed it would not touch, and block the merge in CI.
- As a CI blocking gate, intercept deviations.
Main capabilities
- Through surface-level static analysis, extract what a third-party MCP server can touch: files, network, subprocesses, environment variables.
- When a manifest exists, compare the extraction results against the declared boundaries.
- Result verdict: red (block) indicates a detected deviation, where the code touches paths or capabilities not declared in the manifest; green indicates no deviation, or when there is no manifest, only output the blast-radius report and pass advisory.
Scan scope
- Default scope: production packages only. Exclude tests/, docs/, examples/, scripts/, benchmarks/, .github/, and the test_*.py pattern.
- JSON output includes scan_scope and excluded_file_count.
- Pass --include-peripheral to scan the entire repository.
Usage
Step 1: Scan the server with one command. Point --target-dir at your release package root (for example, src/). The default scope excludes tests, docs, and scripts.
Step 2: Read the JSON output. Undeclared capabilities are usually drift rather than malicious; treat network/subprocess counts as upper bounds, not confirmed traffic.
Step 3: Apply for an audit badge (optional, opt-in). If you have completed a clean scan and want a signed README badge, you can submit a badge application, pasting your command and JSON. Free, 90-day proof, no callback. See BADGE_CRITERIA.md for the standard. Independently verify any published proof: first pip install cryptography, then run packaging/scripts/verify_attestation.py (accepts a local path or HTTPS URL). See the Verify section of BADGE_CRITERIA.md for details.
MCP and CLI
- pipx run mcp-blast-radius starts the MCP stdio server, suitable for Claude Desktop / Cursor.
- For CLI scanning, use mcp-blast-radius-gate.
CI blocking gate
- aos_compliance_validate: scan an MCP server directory (target_dir required; tool_id optional label).
- aos_compliance_self_test: wiring smoke test.
- Default gate_mode=advisory. When using gate_mode=blocking in CI, any deviation fails.
Extracted content
- Surface-level capabilities such as files, network, subprocesses, and environment variables.
Limitations
- Static analysis only. Dynamic imports, getattr / eval, obfuscation, and native extensions may hide capabilities. The tool does not claim complete coverage; each finding carries a confidence label.
Machine-readable metadata
- Agent Card (capabilities, limitations, pricing): agent_card.json
- Catalog entry (pricing, installation, MCP endpoints): aos-standard/catalog
- Specification: AOS-v0.1
Reporting scan issues
- Submit a GitHub issue with the JSON output, and the structured template will load automatically.
