MCP Blast Radius README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the MCP Blast Radius listing page.
MCP Blast-Radius Auditor
See what any MCP server can actually touch — before you add it to your agent.
No manifest? You still get the full blast-radius report. Add a manifest to also catch divergences.
Also, if the server declares a manifest: Catch an MCP server that touches files it said it wouldn't — and block the merge in CI.
Statically extract what a third-party MCP server can reach (files, network, subprocess, env) via surface-level analysis. Compare against declared boundaries when a manifest is present.
Scan scope (default): production package only — excludes tests/, docs/, examples/, scripts/, benchmarks/, .github/, and test_*.py patterns; JSON output includes scan_scope and excluded_file_count. Pass --include-peripheral to scan the full repo.
Try it in 3 steps
① Scan your server in one command
Point --target-dir at your shipping package root (e.g. src/). Default scope excludes tests, docs, and scripts.
② Read the JSON
| Field | What it means |
|---|---|
gate_pass | Scan finished (advisory = report either way; blocking = exit 1 on divergences) |
blocking_reasons | Lines starting with DIVERGENCE: = declared vs. observed mismatch (if you ship a manifest) |
blast_radius | Static capability surface (network, subprocess, env, filesystem) |
confidence labels | declared / observed-static / cannot-determine — static only, upper bounds |
Undeclared capability is usually drift, not malice. Treat network/subprocess counts as upper bounds, not confirmed traffic.
③ Apply for an audit badge (optional, opt-in)
Ran a clean scan and want a signed README badge? Open a badge application — paste your command and JSON. Free, 90-day attestation, no phone-home. Criteria: BADGE_CRITERIA.md.
To verify any published attestation independently: pip install cryptography, then run packaging/scripts/verify_attestation.py (accepts local paths or HTTPS URLs). See BADGE_CRITERIA.md §Verify.
Machine-readable metadata
- Agent Card (capabilities, limitations, pricing): agent_card.json
- Catalog entry (pricing, install, MCP endpoint): aos-standard/catalog
- Spec: AOS-v0.1
Example walkthrough
Inspect blast_radius and any DIVERGENCE: lines in blocking_reasons.
Report a scan question
Open a GitHub issue with your JSON output (structured template loads automatically).
30-second scan
pipx run mcp-blast-radius starts the MCP stdio server (for Claude Desktop / Cursor). For CLI scanning, use mcp-blast-radius-gate as above.
- Red (blocking): divergence detected — code touches paths or capabilities not declared in manifest.
- Green: no divergences (or no manifest — blast radius report only, advisory pass).
Install
CLI entry
CI blocking gate
MCP tools
aos_compliance_validate— scan one MCP server directory (target_dirrequired;tool_idoptional label)aos_compliance_self_test— wiring smoke test
Default gate_mode=advisory. Use gate_mode=blocking in CI to fail on divergences.
What is extracted
| Layer | Scope | Confidence |
|---|---|---|
| Dependencies | requirements.txt, pyproject.toml, package.json | declared |
| Python AST | imports, file I/O, network, env, subprocess; MCP tool attribution | observed-static / cannot-determine |
| Divergence | manifest permitted_output_paths / oracle_paths vs observed access | blocking when mismatch |
Limitations: Static analysis only. Dynamic imports, getattr/eval, obfuscation, and native extensions may hide capabilities. We do not claim complete coverage — every finding includes a confidence label.
Environment
| Variable | Purpose |
|---|---|
AOS_VALIDATOR_TARGET_DIR | Default scan root when target_dir is omitted |
AOS_VALIDATOR_MCP_LOG | JSONL path for local tool call log (never sent externally) |
AOS_VALIDATOR_CALLER | Caller label (ci, smoke_self_call, etc.) |
Example
License
MIT