MSCC — MCP & Agent Security Scanner

Scan the things that inject text into your AI agent's context — before that text becomes an instruction.

MSCC audits the agent-context attack surface: MCP servers, MCP client
configurations, agent skills, and persistent memory files. These are
different artifacts with one shared failure mode — untrusted text crosses a
boundary into an agent's context and is then treated as instruction (a
poisoned tool description, a malicious SKILL.md, a planted line in
CLAUDE.md). MSCC finds that text, including the credential-exfiltration
flows that are written in plain English and have no code signature for a
traditional scanner to match.

What it scans

The headline capability is toxic-flow detection: MSCC flags an artifact
that both instructs the agent to read something sensitive and to send data
out — the shape of a credential-exfiltration attack expressed in prose.

Install

# Core scanner + CLI (no server components)
pip install mscc

# Run without installing (recommended for a one-off machine audit)
uvx mscc surface

Optional extras:

pip install "mscc[pdf]"   # PDF report export
pip install "mscc[api]"   # FastAPI server, Celery workers, Postgres/Redis
pip install "mscc[dev]"   # test + lint toolchain

Requires Python 3.10+.

Quick start

Audit this whole machine

mscc surface

Discovers every MCP client config, installed skill, and agent memory file for
Claude, Cursor, Windsurf, VS Code, Gemini, Codex, Zed and others, scans them
all, and prints a per-source risk table plus any exfiltration flows it finds.

Scan a directory or file

mscc scan ./my-mcp-server
mscc scan ./skills/my-skill/SKILL.md
mscc scan . --profile dev-fast
mscc scan . --max-risk 70 -o results.sarif   # for CI

Scan a Git repository

mscc scan-repo https://github.com/org/mcp-server --branch main --subpath src

Scan a live MCP server

# Launches the server over stdio and audits its advertised tools/prompts.
# Only run servers you trust to start locally.
mscc scan-server "npx -y @modelcontextprotocol/server-github"

Python SDK

from mscc import MSCCClient, scan_local

result = scan_local("./my-mcp-server")
print(f"Risk score: {result.risk_score}/100  ({len(result.findings)} findings)")

for f in result.findings:
    loc = f"{f.file_path}:{f.line_number}" if f.file_path else "-"
    print(f"[{f.severity.value}] {f.title}  ({loc})")

# Export
result.to_sarif()             # dict, ready for GitHub code scanning
open("report.html", "w").write(result.to_html())

An AsyncMSCCClient with the same API (await client.scan(...),
scan_multiple(...)) is available for concurrent scans.

Detection coverage

MSCC combines four detection engines:

• Static patterns — 60+ compiled regex rules across Python, JavaScript/
  TypeScript, Go, Rust, Java, and C#, plus config and prose rules. Rules are
  scoped to the languages they apply to, so a Java rule never fires on a
  Python file.
• Context analysis — prose-oriented detection for skill and memory files:
  toxic flows, standing instructions to read secrets, instruction overrides,
  embedded credentials, and external references loaded into memory.
• YARA rules — packaged rules for the OWASP MCP Top 10 and secret
  detection, extensible with your own .yar files.
• MCP client-config analysis — supply-chain and secret checks on the
  mcpServers blocks of client configuration files.

Findings are mapped to the OWASP MCP Top 10, OWASP ASI06 (persistent
context poisoning), and CWE identifiers where applicable. See
docs/detection-coverage.md for the full rule
catalog.

Suppressing a finding

Add an inline marker on the offending line:

os.system(cmd)  # mscc:ignore                      # suppress all rules here
os.system(cmd)  # mscc:ignore[command-injection-shell]   # suppress one rule

Scan profiles

Reports

Every result exports to JSON, SARIF 2.1.0 (with a populated rule
catalog and repo-relative paths for GitHub code scanning), Markdown,
HTML, an SVG badge, and PDF (mscc[pdf]). All report formats
HTML-escape finding content, so hostile payloads in a scanned file can't
inject into the report.

Output format is chosen by the -o file extension:

mscc scan . -o report.json
mscc scan . -o report.sarif
mscc scan . -o report.html
mscc scan . -o badge.svg

CI/CD

name: MCP Security Scan
on: [push, pull_request]
jobs:
  mscc:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install mscc
      - run: mscc scan . --max-risk 70 -o results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: results.sarif

Exit codes: 0 pass, 1 findings exceeded threshold (or a critical finding),
2 the scan itself failed to run. A failed scan never reports as a pass.
A reusable workflow is provided in
.github/workflows/mscc-scan.yml.

API server (optional)

The mscc[api] extra ships a FastAPI service for centralized scanning.

pip install "mscc[api]"
uvicorn mscc.api.app:app --host 0.0.0.0 --port 8000
# or: docker compose up --build

Deploy it safely — see docs/api.md:

• Set MSCC_API_KEY to require the X-API-Key header (compared in constant time).
• Set MSCC_SCAN_ROOT to confine scanning to one directory. Without it the API
  will scan any path the process can read and echo matched content in findings.
• Set MSCC_CORS_ORIGINS to an explicit origin list in production.

Documentation

Scope & honesty

MSCC is a detection aid, not a proof of safety. Static and prose analysis
have false positives and false negatives; a clean scan is not a guarantee.
Treat findings as leads to review, not verdicts. The roadmap
(SCOPE.md) tracks planned work — including a cross-surface
provenance graph — which is not implemented yet and is not claimed here.

Contributing

See CONTRIBUTING.md. Detection rules live in
src/mscc/scanner/static.py (patterns), src/mscc/scanner/context.py (prose),
and src/mscc/rules/ (YARA).

Security

Report vulnerabilities per SECURITY.md.

License

Apache-2.0 — see LICENSE.