mcp-shark

Security scanner for AI agent tools — built for security and platform engineers working with MCP in the IDE.

Run a local static scan over MCP IDE configs and embedded tool metadata: 41 rules (including AAuth visibility), toxic-flow heuristics, and SARIF / HTML / JSON reports. There is no hosted config-scan backend.

Add an optional local HTTP proxy with an in-browser dashboard so live traffic, findings, AAuth signals, and playground checks stay in one place—without sending your configs to a vendor.

You can

• Use Traffic for live JSON-RPC capture, filters, export, and AAuth posture chips
• Run Local Analysis for OWASP-style findings over captured traffic
• Run YARA Detection for traffic pattern rules (native engine when installed, regex fallback otherwise)
• Open AAuth Explorer for a graph of agents, missions, resources, and signing / access signals
• Use MCP Playground to call tools, prompts, and resources through the proxy
• Optionally run Smart Scan (AI-backed; uses your API token when enabled)
• Use Server setup to detect configs, convert format, and route the editor through the proxy

Privacy: static scans need no cloud and send no telemetry. Refreshing rule catalogs is opt-in HTTPS (update-rules).

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

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

CLI flags

scan (default command)

Other commands

How scan works

The CLI scan command is static: it reads MCP entries from your IDE config files (see Supported IDEs and optional project ./mcp.json) and analyzes what is written there. It does not connect to running MCP servers or call tools/list.

• Always scanned: each server block’s command, args, env, url, and related fields (secrets in env, unsafe spawn patterns, HTTP URLs, etc.).
• Tool-level rules (declarative packs, command-injection heuristics, toxic-flow classification from tool names, etc.) run only when that server entry includes an embedded tools array (name, description, schemas). If tools is omitted—typical for command/stdio-only configs—the scan may report 0 tools checked even though Cursor is running the server fine.

To exercise full rule coverage in CI or test repos, either embed tool metadata in the same JSON your scanner reads, or use a project-local mcp.json harness (see --ide Project).

What it covers

mcp-shark is aimed at config and metadata you already have on disk (plus optional local monitoring). It helps catch common misconfigurations and risky combinations; treat output as input to your own review, not a guarantee nothing is wrong.

Rule Extensibility

Downloadable Rule Packs (JSON)

The canonical registry (manifest, pack files, validation CI, and schema notes) lives in mcp-shark/rule-packs. The npm package embeds copies; update-rules pulls the same artifacts into .mcp-shark/rule-packs/.

mcp-shark ships with 30 declarative rules as JSON packs (OWASP MCP, Agentic Security Initiative, General Security, AAuth Visibility), plus a toxic-flow-heuristics pack (toxic_flow_rules for cross-server composition). New vulnerability catalogs can be added as .json files — no JavaScript, no code changes.

# Fetch latest rule packs from the registry
npx @mcp-shark/mcp-shark update-rules

# Use a custom/enterprise registry
npx @mcp-shark/mcp-shark update-rules --source https://internal.corp/rules/manifest.json

Downloaded packs are cached in .mcp-shark/rule-packs/ and merged with built-in rules on every scan.

{
  "id": "owasp-mcp-2027",
  "name": "OWASP MCP Top 10 (2027)",
  "version": "1.0.0",
  "rules": [
    {
      "id": "MCP01-token-mismanagement",
      "name": "Token Mismanagement",
      "severity": "critical",
      "framework": "OWASP-MCP",
      "description": "Detects hardcoded tokens in MCP configs",
      "patterns": [
        { "regex": "(api[_-]?key|token)\\s*[:=]", "flags": "i", "label": "API key pattern" }
      ],
      "scope": ["tool", "prompt", "resource", "packet"],
      "exclude_patterns": [{ "regex": "\\$\\{|process\\.env" }],
      "match_mode": "any"
    }
  ]
}

Custom YAML Rules (per-project)

Create .mcp-shark/rules/ in your project to add lightweight custom rules:

# .mcp-shark/rules/no-production-keys.yaml
id: custom-no-prod-keys
name: No Production Keys
severity: critical
description: Detects production API keys in MCP configs
match:
  env_pattern: "^(PROD_|PRODUCTION_)"
  value_pattern: "^sk-live|^pk-live"
message: "Production key detected in {key} — use staging keys for development"

Both YAML rules and JSON packs are loaded automatically on scan. Share them with your team by committing the folder.

User-Overridable Data (.mcp-shark/)

Every built-in data source can be extended or overridden through YAML files in your project root:

User data is merged with built-in data at scan time. No rebuild required.

GitHub Action

# .github/workflows/mcp-security.yml
name: MCP Security Scan
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: mcp-shark/scan-action@v1
        with:
          format: sarif
          fail-on: high
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: mcp-shark-results.sarif

Supported IDEs

Security Rules (41)

OWASP MCP Top 10

Agentic Security Initiative (ASI)

AAuth Visibility (informational)

General Security

Browser dashboard

MCP Shark ships an in-browser dashboard on the local proxy for real-time MCP traffic, analysis, and exploration:

npx @mcp-shark/mcp-shark serve --open

Same as the older shortcut (no serve subcommand):

npx @mcp-shark/mcp-shark --open

The dashboard provides:

• Multi-server aggregation and real-time traffic capture (filters, export, AAuth posture chips)
• MCP Playground — call tools, prompts, and resources through the proxy against a selected upstream
• Local Analysis — OWASP-style static scan over captured traffic; YARA Detection for traffic pattern rules (native engine when installed, regex fallback otherwise)
• AAuth Explorer — graph of Agent / Mission / Resource / signing / access signals observed in traffic
• Smart Scan — optional AI-backed scan (requires a configured API token)
• In-app API docs, server setup, logs, and graceful shutdown

Zero-touch first boot

The dashboard bootstraps itself the first time you launch it on a new machine — no Setup wizard click required:

1. If ~/.mcp-shark/mcps.json already declares upstreams (e.g. from a previous run, hand-edit, or testbed:up), the proxy starts directly with that config.
2. Otherwise, on a brand-new install (no ~/.mcp-shark at all), MCP Shark scans for a real editor MCP config (~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json, ~/.codex/config.toml). If one is found with actual upstreams, it auto-imports them, writes ~/.mcp-shark/mcps.json, starts the proxy, and patches the editor config so the editor routes through the proxy.
3. If neither path applies, the UI starts in monitoring-only mode and the Setup panel is still available for manual configuration.

To re-trigger first-boot behavior on a machine, remove ~/.mcp-shark/ and restart the UI.

Architecture

┌────────────────────────────────────────────────────┐
│  CLI (Commander.js)                                │
│  scan · lock · diff · doctor · list · watch · tui  │
│  update-rules · serve                              │
├──────────────┬──────────────┬──────────────────────┤
│  ConfigScanner│  ScanService  │  StaticRulesService  │
│  15 IDEs      │  orchestrator │  41 rules            │
├──────────────┴──────────────┴──────────────────────┤
│  Data layer (JSON + user YAML/JSON overrides)      │
│  ┌────────────┬──────────────┬───────────────────┐ │
│  │ rule-packs │ secret-      │ tool-             │ │
│  │ (30 rules) │ patterns.json│ classifications   │ │
│  ├────────────┼──────────────┼───────────────────┤ │
│  │ toxic-flow │ rule-        │ .mcp-shark/*.yaml │ │
│  │ rules.json │ sources.json │ (user overrides)  │ │
│  └────────────┴──────────────┴───────────────────┘ │
├────────────────────────────────────────────────────┤
│  JS plugins (11 rules needing algorithmic logic)   │
│  + DeclarativeRuleEngine (30 pattern-based rules)  │
└────────────────────────────────────────────────────┘

Design principles:

• Data-first — Declarative rules, secret patterns, tool classifications, and toxic-flow defaults ship as JSON; 30 of 41 rules are pattern packs you can extend or override without forking those definitions.
• User-overridable — Built-in data can be extended via .mcp-shark/*.yaml (and JSON pack drops) as documented above.
• Hybrid rule engine — The other 11 rules are JS plugins where heuristics need code. Both sources are merged at scan time.
• Zero-config scanning — npx and go. Auto-detects the IDE paths below plus project-local mcp.json variants.

Documentation

• Rule pack registry — Official manifest.json and JSON packs consumed by update-rules
• Getting Started — Installation & setup
• Features — Detailed feature documentation
• User Guide — Complete usage guide
• Configuration — Configuration files & environment variables
• Local Analysis — Static security analysis & YARA traffic rules
• AAuth Visibility — RFC 9421 / AAuth observability
• Architecture — System design
• Database Architecture — SQLite schema reference
• API Reference — API endpoints
• Troubleshooting — Common issues & fixes
• Development — Contributing & project conventions
• Package inspection — npm package layout

Requirements

• Node.js: 20.0.0 or higher
• OS: macOS, Windows, or Linux

License

Source-Available Non-Commercial License

• ✅ View, fork, modify, run for personal, educational, or internal company use
• ❌ Sell, resell, or integrate into paid products/services without written permission

See LICENSE for full terms.

CLI demo

Same one-liner as Quick Start (default scan). Terminal output depends on your config:

npx @mcp-shark/mcp-shark

Support

• Issues: GitHub Issues
• Website: mcpshark.sh