mcp-shark

Dashboard at a glance

These captures are from the live dashboard with real captured traffic (dummy MCP or your own upstreams). Start with npx @mcp-shark/mcp-shark serve --open. Smart Scan is not shown below — it depends on an optional remote API token. MCP Playground appears once you have at least one MCP upstream configured (the Playground capture uses a demo server with tools loaded).

Live traffic capture

Every JSON-RPC frame between your IDE and each MCP upstream is captured with full headers, body, timing, and an AAuth posture chip. Filter by method, status, server, session, AAuth agent / mission / posture.

MCP Playground

Pick an upstream, load tools, prompts, and resources from that server, then call tools or read resources through the proxy — useful for validating behavior before it hits your IDE. The view below shows the tools list for a configured demo MCP.

AAuth Explorer

Force-directed knowledge graph of every Agent / Mission / Resource / Signing algorithm / Access mode observed across captured traffic. Use Generate sample data for a quick demo graph, or capture real AAuth-shaped traffic through the proxy.

Local Analysis

Offline rule-based scanner over captured traffic. The AAuth Posture card summarizes signed / aauth-aware / bearer / no-auth distribution; the Toxic flows (proxy traffic) panel infers cross-server pairings from observed tools/list responses. With packets already in the database, use Replay from DB (when no live MCP is attached) and then Analyse to populate findings — the view below is after that run.

YARA Detection

Same Local Analysis tab: switch to YARA Detection for the traffic rule engine — engine status, eight predefined rules (toggle, edit, delete), and New Rule for your own patterns. When the native yara module is not installed, scans still run using the built-in regex fallback (see docs/local-analysis.md).

New Rule opens the editor with a starter template (meta, strings, and condition). Edit the rule text, then Save Rule to add it as a custom pattern alongside the built-ins.

Server setup

Auto-detects Cursor / Codex / Windsurf configs, converts them to mcp-shark format, and patches the IDE to route through the proxy on start.

Why mcp-shark?

MCP setups commonly mix secrets, broad tool access, and multiple servers in one agent context; issues are easy to miss without checking configs. See the OWASP MCP Top 10 for a structured view of what can go wrong.

mcp-shark runs on your machine — no API keys or hosted scan backend. Install with npx and review findings locally.

Toxic flow analysis

The scanner models how MCP servers compose in the agent context and flags risky capability pairings (for example, secret access combined with external egress):

  ▲ HIGH  notify-server → repo-server
    Untrusted content in one tool’s channel could lead the agent to
    take a destructive action in another (e.g. push code).

  ▲ MEDIUM  browser-server → filesystem-server
    Web-sourced context could be chained into local file operations.

Use mcp-shark findings as input to your own threat model, not as a complete audit.

Features

| Feature | Description | |---------|-------------| | 41 security rules | OWASP MCP Top 10 + Agentic Security Initiative + AAuth visibility + general checks | | Toxic flow analysis | Cross-server attack path detection from tool capability heuristics | | Attack walkthroughs | Step-by-step exploit narratives from findings | | Shark Score | Transparent security posture score (0-100, A-F) | | Auto-fix | --fix replaces hardcoded secrets, fixes permissions, with backup/undo | | Tool pinning | Git-committable .mcp-shark.lock with SHA-256 hashes | | 15 IDE detection | Cursor, Claude Desktop, VS Code, Windsurf, Codex, Amp, Kiro, and more | | 4 output formats | Terminal, JSON, SARIF v2.1.0, HTML | | Health checks | doctor command for environment validation | | Server inventory | list command shows all servers in a table | | Watch mode | Live re-scan on config changes | | HTML reports | Self-contained offline security reports | | Downloadable rule packs | Rule pack registry (manifest + JSON); update-rules syncs declarative packs and toxic-flow heuristics — zero code changes | | YAML rules | Per-project custom rules via .mcp-shark/rules/ | | GitHub Action | CI/CD integration with SARIF upload | | Interactive TUI | lazygit-style terminal UI for scan, fix, and server browsing | | Browser dashboard | Live traffic, Local Analysis, YARA rules, AAuth Explorer, Playground, setup, and logs | | Proxy toxic flows | Local Analysis panel + GET/POST /api/security/traffic-toxic-flows* infer cross-server pairs from captured tools/list traffic (see docs/local-analysis.md) | | YARA-style traffic rules | In Local Analysis → YARA Detection, enable or edit built-in pattern rules, add custom rules, and inspect engine status (native YARA when available, regex fallback otherwise) | | Local static scans | No hosted scan backend; update-rules is opt-in HTTPS to the registry |

Quick Start

# Scan your MCP setup (default command)
npx @mcp-shark/mcp-shark

# Auto-fix issues (with interactive confirmation)
npx @mcp-shark/mcp-shark scan --fix

# See full attack chain narratives
npx @mcp-shark/mcp-shark scan --walkthrough

# Pin tool definitions (lockfile) to spot unexpected changes
npx @mcp-shark/mcp-shark lock

# Check environment health
npx @mcp-shark/mcp-shark doctor

# Show all detected servers
npx @mcp-shark/mcp-shark list

# Download latest rule packs (OWASP, Agentic Security)
npx @mcp-shark/mcp-shark update-rules

# Watch for config changes
npx @mcp-shark/mcp-shark watch

# Interactive terminal UI
npx @mcp-shark/mcp-shark tui

# Generate HTML report
npx @mcp-shark/mcp-shark scan --format html --output report.html

# CI mode (exits 1 on critical/high)
npx @mcp-shark/mcp-shark scan --ci --format sarif

Commands

| Command | Description | |---------|-------------| | scan (default) | Run security scan with 41 rules | | lock | Create .mcp-shark.lock file | | lock --verify | Verify current state matches lockfile | | diff | Show tool definition changes since last lock | | doctor | Run environment health checks | | list | Show inventory of all detected servers (--format json supported) | | update-rules | Download latest rule packs from remote registry | | watch | Watch config files and re-scan on changes | | tui | Interactive terminal UI (lazygit-style) | | serve | Start the local proxy and monitoring dashboard |

CLI flags

scan (default command)

| Flag | Description | |------|-------------| | --fix | Auto-fix issues (interactive confirmation) | | --fix --yes | Auto-fix without prompting | | --fix --undo | Restore backups from previous fix | | --walkthrough | Show full attack chain narratives | | --ci | CI mode: exit code 1 on critical/high | | --format <fmt> | Output: terminal, json, sarif, html | | --output <path> | Write report to file (for html format) | | --strict | Count advisory findings in