Skip to content
Back to search

mcp-shark

Wireshark-like forensic analysis for Model Context Protocol communications Capture, inspect, and investigate all HTTP requests and responses between your IDE and MCP servers

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mcp-shark--mcp-shark/badge.svg)](/listings/mcp-shark--mcp-shark)

HTML

<a href="/listings/mcp-shark--mcp-shark"><img src="/api/listings/mcp-shark--mcp-shark/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 524 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="https://smart.mcpshark.sh/icon_512x512.png" alt="MCP Shark Logo" width="128" height="128">
  3. <h1>mcp-shark</h1>
  4. <div style="text-align: left; max-width: 42rem; margin: 0 auto;">
  5. <p><strong>Security scanner for AI agent tools</strong> — built for security and platform engineers working with MCP in the IDE.</p>
  6. <p>Run a local static <code>scan</code> over MCP <strong>IDE configs</strong> and embedded tool metadata: <strong>41 rules</strong> (including <strong>AAuth visibility</strong>), toxic-flow heuristics, and <strong>SARIF</strong> / <strong>HTML</strong> / <strong>JSON</strong> reports. There is no hosted config-scan backend.</p>
  7. <p>Add an optional <strong>local HTTP proxy</strong> with an <strong>in-browser dashboard</strong> so live traffic, findings, AAuth signals, and playground checks stay in one place—without sending your configs to a vendor.</p>
  8. <p><strong>You can</strong></p>
  9. <ul style="margin: 0.35rem 0 0.75rem; padding-left: 1.25rem;">
  10. <li>Use <strong>Traffic</strong> for live JSON-RPC capture, filters, export, and AAuth posture chips</li>
  11. <li>Run <strong>Local Analysis</strong> for OWASP-style findings over captured traffic</li>
  12. <li>Run <strong>YARA Detection</strong> for traffic pattern rules (native engine when installed, regex fallback otherwise)</li>
  13. <li>Open <strong>AAuth Explorer</strong> for a graph of agents, missions, resources, and signing / access signals</li>
  14. <li>Use <strong>MCP Playground</strong> to call tools, prompts, and resources through the proxy</li>
  15. <li>Optionally run <strong>Smart Scan</strong> (AI-backed; uses <strong>your</strong> API token when enabled)</li>
  16. <li>Use <strong>Server setup</strong> to detect configs, convert format, and route the editor through the proxy</li>
  17. </ul>
  18. <p><strong>Privacy:</strong> static scans need no cloud and send no telemetry. Refreshing rule catalogs is opt-in HTTPS (<code>update-rules</code>).</p>
  19. </div>
  20. [![npm version](https://img.shields.io/npm/v/@mcp-shark/mcp-shark.svg)](https://www.npmjs.com/package/@mcp-shark/mcp-shark)
  21. [![License: Non-Commercial](https://img.shields.io/badge/License-Non--Commercial-red.svg)](LICENSE)
  22. </div>
  23. ## Dashboard at a glance
  24. 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).
  25. ### Live traffic capture
  26. 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.
  27. ![Traffic Capture](docs/assets/hero-traffic.png)
  28. ### MCP Playground
  29. 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.
  30. ![MCP Playground](docs/assets/playground.png)
  31. ### AAuth Explorer
  32. 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.
  33. ![AAuth Explorer](docs/assets/aauth-explorer.png)
  34. ### Local Analysis
  35. 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.
  36. ![Local Analysis](docs/assets/local-analysis.png)
  37. ### YARA Detection
  38. 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](docs/local-analysis.md)).
  39. ![YARA Detection](docs/assets/yara-detection.png)
  40. **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.
  41. ![Adding a custom YARA rule](docs/assets/yara-new-rule.png)
  42. ### Server setup
  43. Auto-detects Cursor / Codex / Windsurf configs, converts them to mcp-shark format, and patches the IDE to route through the proxy on start.
  44. ![Server Setup](docs/assets/setup.png)
  45. ## Why mcp-shark?
  46. 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](https://owasp.org/www-project-mcp-top-10/) for a structured view of what can go wrong.
  47. mcp-shark runs on your machine — no API keys or hosted scan backend. Install with `npx` and review findings locally.
  48. ### Toxic flow analysis
  49. The scanner models how MCP servers **compose in the agent context** and flags risky capability pairings (for example, secret access combined with external egress):
  50. ```
  51. ▲ HIGH notify-server → repo-server
  52. Untrusted content in one tool’s channel could lead the agent to
  53. take a destructive action in another (e.g. push code).
  54. ▲ MEDIUM browser-server → filesystem-server
  55. Web-sourced context could be chained into local file operations.
  56. ```
  57. Use mcp-shark findings as input to your own threat model, not as a complete audit.
  58. ## Features
  59. | Feature | Description |
  60. |---------|-------------|
  61. | **41 security rules** | OWASP MCP Top 10 + Agentic Security Initiative + AAuth visibility + general checks |
  62. | **Toxic flow analysis** | Cross-server attack path detection from tool capability heuristics |
  63. | **Attack walkthroughs** | Step-by-step exploit narratives from findings |
  64. | **Shark Score** | Transparent security posture score (0-100, A-F) |
  65. | **Auto-fix** | `--fix` replaces hardcoded secrets, fixes permissions, with backup/undo |
  66. | **Tool pinning** | Git-committable `.mcp-shark.lock` with SHA-256 hashes |
  67. | **15 IDE detection** | Cursor, Claude Desktop, VS Code, Windsurf, Codex, Amp, Kiro, and more |
  68. | **4 output formats** | Terminal, JSON, SARIF v2.1.0, HTML |
  69. | **Health checks** | `doctor` command for environment validation |
  70. | **Server inventory** | `list` command shows all servers in a table |
  71. | **Watch mode** | Live re-scan on config changes |
  72. | **HTML reports** | Self-contained offline security reports |
  73. | **Downloadable rule packs** | [Rule pack registry](https://github.com/mcp-shark/rule-packs) (manifest + JSON); `update-rules` syncs declarative packs and toxic-flow heuristics — zero code changes |
  74. | **YAML rules** | Per-project custom rules via `.mcp-shark/rules/` |
  75. | **GitHub Action** | CI/CD integration with SARIF upload |
  76. | **Interactive TUI** | lazygit-style terminal UI for scan, fix, and server browsing |
  77. | **Browser dashboard** | Live traffic, Local Analysis, YARA rules, AAuth Explorer, Playground, setup, and logs |
  78. | **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](docs/local-analysis.md)) |
  79. | **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) |
  80. | **Local static scans** | No hosted scan backend; `update-rules` is opt-in HTTPS to the registry |
  81. ## Quick Start
  82. ```bash
  83. # Scan your MCP setup (default command)
  84. npx @mcp-shark/mcp-shark
  85. # Auto-fix issues (with interactive confirmation)
  86. npx @mcp-shark/mcp-shark scan --fix
  87. # See full attack chain narratives
  88. npx @mcp-shark/mcp-shark scan --walkthrough
  89. # Pin tool definitions (lockfile) to spot unexpected changes
  90. npx @mcp-shark/mcp-shark lock
  91. # Check environment health
  92. npx @mcp-shark/mcp-shark doctor
  93. # Show all detected servers
  94. npx @mcp-shark/mcp-shark list
  95. # Download latest rule packs (OWASP, Agentic Security)
  96. npx @mcp-shark/mcp-shark update-rules
  97. # Watch for config changes
  98. npx @mcp-shark/mcp-shark watch
  99. # Interactive terminal UI
  100. npx @mcp-shark/mcp-shark tui
  101. # Generate HTML report
  102. npx @mcp-shark/mcp-shark scan --format html --output report.html
  103. # CI mode (exits 1 on critical/high)
  104. npx @mcp-shark/mcp-shark scan --ci --format sarif
  105. ```
  106. ## Commands
  107. | Command | Description |
  108. |---------|-------------|
  109. | `scan` (default) | Run security scan with 41 rules |
  110. | `lock` | Create `.mcp-shark.lock` file |
  111. | `lock --verify` | Verify current state matches lockfile |
  112. | `diff` | Show tool definition changes since last lock |
  113. | `doctor` | Run environment health checks |
  114. | `list` | Show inventory of all detected servers (`--format json` supported) |
  115. | `update-rules` | Download latest rule packs from remote registry |
  116. | `watch` | Watch config files and re-scan on changes |
  117. | `tui` | Interactive terminal UI (lazygit-style) |
  118. | `serve` | Start the local proxy and monitoring dashboard |
  119. ## CLI flags
  120. ### `scan` (default command)
  121. | Flag | Description |
  122. |------|-------------|
  123. | `--fix` | Auto-fix issues (interactive confirmation) |
  124. | `--fix --yes` | Auto-fix without prompting |
  125. | `--fix --undo` | Restore backups from previous fix |
  126. | `--walkthrough` | Show full attack chain narratives |
  127. | `--ci` | CI mode: exit code 1 on critical/high |
  128. | `--format <fmt>` | Output: `terminal`, `json`, `sarif`, `html` |
  129. | `--output <path>` | Write report to file (for `html` format) |
  130. | `--strict` | Count advisory findings in score |
  131. | `--ide <name>` | Scan specific IDE only |
  132. | `--rules <path>` | Load custom YAML rules from directory |
  133. | `--refresh-rules` | Fetch rule packs from registry before scan (HTTPS; see rule registry config) |
  134. ### Other commands
  135. | Command | Flags / notes |
  136. |---------|----------------|
  137. | `list` | `--format terminal` or `--format json` |
  138. | `update-rules` | `--source <url>` for a custom pack manifest |
  139. | `serve` | `--open` / `-o` to open the browser |
  140. | `lock` | `--verify` to check lockfile match |
  141. ## How `scan` works
  142. The CLI **`scan`** command is **static**: it reads MCP entries from your IDE config files (see [Supported IDEs](#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`.
  143. - **Always scanned:** each server block’s `command`, `args`, `env`, `url`, and related fields (secrets in `env`, unsafe spawn patterns, HTTP URLs, etc.).
  144. - **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.
  145. 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`).
  146. ## What it covers
  147. 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.
  148. | Area | Notes |
  149. |------|--------|
  150. | Install / run | Node.js 20+; `npx @mcp-shark/mcp-shark` |
  151. | Security rules | 41 checks — 30 declarative JSON packs, 11 JS where heuristics need code |
  152. | Toxic flow analysis | Heuristic cross-server paths; quality depends on embedded `tools` / classifications |
  153. | Attack walkthroughs | Narratives derived from findings |
  154. | Auto-fix | Supported for a subset of issues; confirm changes in your repo |
  155. | Tool pinning | `.mcp-shark.lock` with SHA-256 hashes |
  156. | Live traffic | Dashboard (`serve`) for monitoring; separate from static `scan` |
  157. | Custom rules | YAML under `.mcp-shark/rules/` and JSON rule packs |
  158. | Findings & score | confirmed / advisory tiers plus Shark Score (0–100, A–F) |
  159. | IDE configs | 15 built-in paths + project-local `mcp.json` variants — see [Supported IDEs](#supported-ides) |
  160. | Output | Terminal, JSON, SARIF v2.1.0, HTML |
  161. | Health | `doctor` for environment checks |
  162. | CI | `scan --ci` and optional [GitHub Action](#github-action) |
  163. | Watch | Re-scan when config files change |
  164. | Rule updates | `update-rules` (optional HTTPS fetch; static scan works without it) |
  165. ## Rule Extensibility
  166. ### Downloadable Rule Packs (JSON)
  167. The canonical **registry** (manifest, pack files, validation CI, and schema notes) lives in **[mcp-shark/rule-packs](https://github.com/mcp-shark/rule-packs)**. The npm package embeds copies; `update-rules` pulls the same artifacts into `.mcp-shark/rule-packs/`.
  168. 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.
  169. ```bash
  170. # Fetch latest rule packs from the registry
  171. npx @mcp-shark/mcp-shark update-rules
  172. # Use a custom/enterprise registry
  173. npx @mcp-shark/mcp-shark update-rules --source https://internal.corp/rules/manifest.json
  174. ```
  175. Downloaded packs are cached in `.mcp-shark/rule-packs/` and merged with built-in rules on every scan.
  176. <details>
  177. <summary>Rule pack JSON schema</summary>
  178. ```json
  179. {
  180. "id": "owasp-mcp-2027",
  181. "name": "OWASP MCP Top 10 (2027)",
  182. "version": "1.0.0",
  183. "rules": [
  184. {
  185. "id": "MCP01-token-mismanagement",
  186. "name": "Token Mismanagement",
  187. "severity": "critical",
  188. "framework": "OWASP-MCP",
  189. "description": "Detects hardcoded tokens in MCP configs",
  190. "patterns": [
  191. { "regex": "(api[_-]?key|token)\\s*[:=]", "flags": "i", "label": "API key pattern" }
  192. ],
  193. "scope": ["tool", "prompt", "resource", "packet"],
  194. "exclude_patterns": [{ "regex": "\\$\\{|process\\.env" }],
  195. "match_mode": "any"
  196. }
  197. ]
  198. }
  199. ```
  200. </details>
  201. ### Custom YAML Rules (per-project)
  202. Create `.mcp-shark/rules/` in your project to add lightweight custom rules:
  203. ```yaml
  204. # .mcp-shark/rules/no-production-keys.yaml
  205. id: custom-no-prod-keys
  206. name: No Production Keys
  207. severity: critical
  208. description: Detects production API keys in MCP configs
  209. match:
  210. env_pattern: "^(PROD_|PRODUCTION_)"
  211. value_pattern: "^sk-live|^pk-live"
  212. message: "Production key detected in {key} — use staging keys for development"
  213. ```
  214. Both YAML rules and JSON packs are loaded automatically on scan. Share them with your team by committing the folder.
  215. ### User-Overridable Data (`.mcp-shark/`)
  216. Every built-in data source can be extended or overridden through YAML files in your project root:
  217. | File | Overrides | Format |
  218. |------|-----------|--------|
  219. | `.mcp-shark/secrets.yaml` | Secret detection patterns | List of `{ name, regex }` |
  220. | `.mcp-shark/classifications.yaml` | Server/tool capability tags | Nested map `server: { capability: true }` |
  221. | `.mcp-shark/flows.yaml` | Toxic flow rules | List of `{ source_cap, target_cap, risk, ... }` |
  222. | `.mcp-shark/rules/*.yaml` | Custom per-project rules | See YAML Rules above |
  223. | `.mcp-shark/rule-packs/*.json` | Override or add declarative packs | See JSON Packs above |
  224. User data is merged with built-in data at scan time. No rebuild required.
  225. ## GitHub Action
  226. ```yaml
  227. # .github/workflows/mcp-security.yml
  228. name: MCP Security Scan
  229. on: [push, pull_request]
  230. jobs:
  231. scan:
  232. runs-on: ubuntu-latest
  233. steps:
  234. - uses: actions/checkout@v4
  235. - uses: mcp-shark/scan-action@v1
  236. with:
  237. format: sarif
  238. fail-on: high
  239. - uses: github/codeql-action/upload-sarif@v3
  240. if: always()
  241. with:
  242. sarif_file: mcp-shark-results.sarif
  243. ```
  244. ## Supported IDEs
  245. | IDE | Config Path | Status |
  246. |-----|-------------|--------|
  247. | Cursor | `~/.cursor/mcp.json` | ✅ |
  248. | Claude Desktop | `~/Library/.../claude_desktop_config.json` | ✅ |
  249. | Claude Code | `~/.claude.json` | ✅ |
  250. | VS Code | `~/.vscode/mcp.json` | ✅ |
  251. | Windsurf | `~/.codeium/windsurf/mcp_config.json` | ✅ |
  252. | Codex | `~/.codex/config.toml` | ✅ |
  253. | Gemini CLI | `~/.gemini/settings.json` | ✅ |
  254. | Continue | `~/.continue/config.json` | ✅ |
  255. | Cline | `~/.../saoudrizwan.claude-dev/.../cline_mcp_settings.json` | ✅ |
  256. | Amp | `~/.amp/mcp.json` | ✅ |
  257. | Kiro | `~/.kiro/mcp.json` | ✅ |
  258. | Zed | `~/.config/zed/settings.json` | ✅ |
  259. | Augment | `~/.augment/mcp.json` | ✅ |
  260. | Roo Code | `~/.roo-code/mcp.json` | ✅ |
  261. | Project (local) | `./mcp.json`, `./.mcp.json`, `./.mcp/config.json` | ✅ |
  262. ## Security Rules (41)
  263. <details>
  264. <summary>Full rule list</summary>
  265. ### OWASP MCP Top 10
  266. | ID | Rule | Severity | Source |
  267. |----|------|----------|--------|
  268. | MCP01 | Token Mismanagement | Critical | declarative |
  269. | MCP02 | Scope Creep | High | declarative |
  270. | MCP03 | Tool Poisoning | Critical | declarative |
  271. | MCP04 | Supply Chain | High | declarative |
  272. | MCP05 | Command Injection | Critical | JS plugin |
  273. | MCP06 | Prompt Injection | High | declarative |
  274. | MCP07 | Insufficient Auth | High | declarative |
  275. | MCP08 | Lack of Audit | Medium | declarative |
  276. | MCP09 | Shadow Servers | High | declarative |
  277. | MCP10 | Context Injection | High | declarative |
  278. ### Agentic Security Initiative (ASI)
  279. | ID | Rule | Severity | Source |
  280. |----|------|----------|--------|
  281. | ASI01 | Goal Hijack | Critical | declarative |
  282. | ASI02 | Tool Misuse | High | declarative |
  283. | ASI03 | Identity Abuse | High | declarative |
  284. | ASI04 | Supply Chain | High | declarative |
  285. | ASI05 | Remote Code Execution | Critical | JS plugin |
  286. | ASI06 | Memory Poisoning | High | declarative |
  287. | ASI07 | Insecure Communication | Medium | declarative |
  288. | ASI08 | Cascading Failures | Medium | declarative |
  289. | ASI09 | Trust Exploitation | High | declarative |
  290. | ASI10 | Rogue Agent | Critical | declarative |
  291. ### AAuth Visibility (informational)
  292. | ID | Description | Severity |
  293. |----|-------------|----------|
  294. | `aauth-agent-identity-observed` | `aauth:<local>@<domain>` agent identity in tool/prompt/resource/packet | Low |
  295. | `aauth-jwks-discovery-url` | URLs containing `/.well-known/aauth` or `/jwks` | Low |
  296. | `aauth-http-message-signature-observed` | RFC 9421 `Signature-Input` / `Signature` headers in captured traffic | Low |
  297. | `aauth-mission-context-observed` | `AAuth-Mission` headers in captured traffic | Low |
  298. | `aauth-requirement-challenge-observed` | `AAuth-Requirement` response headers (resource asking for AAuth) | Low |
  299. | `aauth-bearer-token-coexists-with-aauth` | Same packet has both Bearer token and AAuth signature | Medium |
  300. ### General Security
  301. | Rule | Severity |
  302. |------|----------|
  303. | Hardcoded Secrets | Critical |
  304. | Command Injection | Critical |
  305. | Cross-Server Shadowing | High |
  306. | Tool Name Ambiguity | Medium |
  307. | DNS Rebinding | High |
  308. | ANSI Escape Sequences | Medium |
  309. | Config File Permissions | Medium |
  310. | Missing Containment | High |
  311. | Duplicate Tool Names | Medium |
  312. | Shell/Env Injection | High |
  313. | Excessive Permissions | High |
  314. | Unsafe Default Config | Medium |
  315. | Path Traversal | High |
  316. | Sensitive Data Exposure | High |
  317. | Insecure Transport | Medium |
  318. </details>
  319. ## Browser dashboard
  320. MCP Shark ships an **in-browser dashboard** on the local proxy for real-time MCP traffic, analysis, and exploration:
  321. ```bash
  322. npx @mcp-shark/mcp-shark serve --open
  323. ```
  324. Same as the older shortcut (no `serve` subcommand):
  325. ```bash
  326. npx @mcp-shark/mcp-shark --open
  327. ```
  328. The dashboard provides:
  329. - Multi-server aggregation and real-time traffic capture (filters, export, AAuth posture chips)
  330. - **MCP Playground** — call tools, prompts, and resources through the proxy against a selected upstream
  331. - **Local Analysis** — OWASP-style static scan over captured traffic; **YARA Detection** for traffic pattern rules (native engine when installed, regex fallback otherwise)
  332. - **AAuth Explorer** — graph of Agent / Mission / Resource / signing / access signals observed in traffic
  333. - **Smart Scan** — optional AI-backed scan (requires a configured API token)
  334. - In-app API docs, server setup, logs, and graceful shutdown
  335. ### Zero-touch first boot
  336. The dashboard bootstraps itself the first time you launch it on a new machine — no Setup wizard click required:
  337. 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.
  338. 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.
  339. 3. If neither path applies, the UI starts in monitoring-only mode and the Setup panel is still available for manual configuration.
  340. To re-trigger first-boot behavior on a machine, remove `~/.mcp-shark/` and restart the UI.
  341. ## Architecture
  342. ```
  343. ┌────────────────────────────────────────────────────┐
  344. │ CLI (Commander.js) │
  345. │ scan · lock · diff · doctor · list · watch · tui │
  346. │ update-rules · serve │
  347. ├──────────────┬──────────────┬──────────────────────┤
  348. │ ConfigScanner│ ScanService │ StaticRulesService │
  349. │ 15 IDEs │ orchestrator │ 41 rules │
  350. ├──────────────┴──────────────┴──────────────────────┤
  351. │ Data layer (JSON + user YAML/JSON overrides) │
  352. │ ┌────────────┬──────────────┬───────────────────┐ │
  353. │ │ rule-packs │ secret- │ tool- │ │
  354. │ │ (30 rules) │ patterns.json│ classifications │ │
  355. │ ├────────────┼──────────────┼───────────────────┤ │
  356. │ │ toxic-flow │ rule- │ .mcp-shark/*.yaml │ │
  357. │ │ rules.json │ sources.json │ (user overrides) │ │
  358. │ └────────────┴──────────────┴───────────────────┘ │
  359. ├────────────────────────────────────────────────────┤
  360. │ JS plugins (11 rules needing algorithmic logic) │
  361. │ + DeclarativeRuleEngine (30 pattern-based rules) │
  362. └────────────────────────────────────────────────────┘
  363. ```
  364. **Design principles:**
  365. - **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.
  366. - **User-overridable** — Built-in data can be extended via `.mcp-shark/*.yaml` (and JSON pack drops) as documented above.
  367. - **Hybrid rule engine** — The other **11** rules are JS plugins where heuristics need code. Both sources are merged at scan time.
  368. - **Zero-config scanning** — `npx` and go. Auto-detects the IDE paths below plus project-local `mcp.json` variants.
  369. ## Documentation
  370. - **[Rule pack registry](https://github.com/mcp-shark/rule-packs)** — Official `manifest.json` and JSON packs consumed by `update-rules`
  371. - **[Getting Started](docs/getting-started.md)** — Installation & setup
  372. - **[Features](docs/features.md)** — Detailed feature documentation
  373. - **[User Guide](docs/user-guide.md)** — Complete usage guide
  374. - **[Configuration](docs/configuration.md)** — Configuration files & environment variables
  375. - **[Local Analysis](docs/local-analysis.md)** — Static security analysis & YARA traffic rules
  376. - **[AAuth Visibility](docs/aauth-visibility.md)** — RFC 9421 / AAuth observability
  377. - **[Architecture](docs/architecture.md)** — System design
  378. - **[Database Architecture](docs/database-architecture.md)** — SQLite schema reference
  379. - **[API Reference](docs/api-reference.md)** — API endpoints
  380. - **[Troubleshooting](docs/troubleshooting.md)** — Common issues & fixes
  381. - **[Development](docs/development.md)** — Contributing & project conventions
  382. - **[Package inspection](docs/package-inspection.md)** — npm package layout
  383. ## Requirements
  384. - **Node.js**: 20.0.0 or higher
  385. - **OS**: macOS, Windows, or Linux
  386. ## License
  387. Source-Available Non-Commercial License
  388. - ✅ View, fork, modify, run for personal, educational, or internal company use
  389. - ❌ Sell, resell, or integrate into paid products/services without written permission
  390. See [LICENSE](LICENSE) for full terms.
  391. ## CLI demo
  392. Same one-liner as **[Quick Start](#quick-start)** (default `scan`). Terminal output depends on your config:
  393. ```bash
  394. npx @mcp-shark/mcp-shark
  395. ```
  396. ![mcp-shark demo](docs/assets/demo.gif)
  397. ## Support
  398. - **Issues**: [GitHub Issues](https://github.com/mcp-shark/mcp-shark/issues)
  399. - **Website**: [mcpshark.sh](https://mcpshark.sh)
  400. ---
  401. <div align="center">
  402. <strong>MCP servers can chain through the agent — mcp-shark surfaces risky combinations in config and traffic.</strong>
  403. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.