medusa-mcp 2.1.0

Endpoint security agent for Model Context Protocol (MCP) servers

Open-source endpoint DLP for Model Context Protocol (MCP)

AI assistants — Claude Desktop, Cursor, Codex, Claude Code — now use tools through MCP servers, and most security teams have no idea what data flows through them. Medusa is a CLI agent that sits between every AI assistant and every MCP server, scans the traffic on-device for secrets, PII, and 9 more categories of sensitive data, and blocks or redacts what shouldn't leave.

It runs 100% locally. No account, no cloud, no telemetry — unless you choose to connect one.

---

Install

The agent installs in standalone mode — local policy, local event store, zero network calls.

# One-liner (macOS / Linux)
curl -fsSL https://raw.githubusercontent.com/joshmaster2165/medusa-agent/main/packaging/install.sh | sh

# Homebrew
brew tap joshmaster2165/medusa
brew install medusa-agent

# pip / pipx
pipx install medusa-mcp
medusa-agent install

Native signed installers (.pkg / .deb / .msi) are on the releases page.

Verify it:

medusa-agent doctor

That's it. The agent has auto-discovered every MCP client on the machine, wrapped each server with a gateway proxy, and is enforcing DLP policy from ~/.medusa/gateway-policy.yaml.

---

How it works

   AI assistant                  Medusa gateway proxy                MCP server
  (Cursor, Claude   ──JSON-RPC──▶   ┌────────────────────┐  ──────▶  (filesystem,
   Desktop, Codex)                  │  Policy engine     │            Supabase,
                                    │  ALLOW / BLOCK /   │            Stripe, …)
                                    │  COACH  / REDACT   │
                                    │        │           │
                                    │  DLP scanner       │
                                    │  on-device model   │
                                    │  + regex patterns  │
                                    │        │           │
                                    │  WriteAccumulator  │
                                    │  cross-request     │
                                    │  evasion detection │
                                    └────────────────────┘

Every JSON-RPC message — request and response, stdio and Streamable HTTP — is intercepted and evaluated. Nothing is sent anywhere; inference runs on the CPU.

---

What it catches

• 9 DLP categories via an on-device ONNX model: secrets, PII, financial, health/PHI, source code, legal, insurance, HR, business-confidential — plus prompt-injection detection on tool results.
• Deterministic regex detectors for SSN, credit card, AWS keys, GitHub tokens, RSA private keys, email, phone, and more — fire at confidence 1.0 alongside the model.
• Cross-request evasion — WriteAccumulator reassembles content split across multiple write_file / append_file / edit_file calls and rescans the whole thing, so an agent can't smuggle a secret out one chunk at a time.
• Tamper resistance — the agent detects and auto-repairs attempts to strip its own gateway wrapper from MCP config files, and refuses tool calls that target its protected paths.

Verdicts: ALLOW (forward unchanged) · BLOCK (stop at the gateway) · REDACT (forward with sensitive spans masked) · COACH (block + tell the LLM agent why, so it stops retrying).

---

Standalone vs connected

	Standalone (default)	Connected
Account	None	API key from a control plane
Network	Zero calls	Policy sync + telemetry
Policy	Local gateway-policy.yaml	Pushed from the control plane
Events	Local SQLite only	Uploaded to a dashboard

A control plane is an optional service that distributes policy to a fleet of agents and aggregates their telemetry — useful once you're running Medusa on more than one machine. It can be Medusa's hosted dashboard or a self-hosted one; the agent speaks the same open Control Plane API either way.

# Attach this agent to a control plane
medusa-agent connect --control-plane <url> --api-key <key>

# Detach — back to fully local
medusa-agent disconnect

The agent is open source and free, forever. The fleet dashboard is the commercial product.

---

CLI

Command	Description
medusa-agent install	Install the agent (standalone by default)
medusa-agent doctor	Run diagnostic checks
medusa-agent connect	Attach to a control plane
medusa-agent disconnect	Detach — back to standalone
medusa-agent download-model	Fetch the DLP model (pip installs)
medusa-agent status	Daemon health, proxy count, policy version
medusa-agent monitor	Security posture and findings
medusa-agent test	Dry-run a tool call against the policy
medusa-agent logs	Tail the agent log (-f to follow)
medusa-agent start / stop / restart	Daemon control
medusa-agent store list / stats / clear	Local event store
medusa-agent uninstall	Remove the agent

---

Gateway policy

A standalone agent reads ~/.medusa/gateway-policy.yaml:

block_secrets: true
block_pii: true
block_financial: true
block_health: true
block_injections: true
scan_responses: true
coaching_enabled: true
sandbox_mode: false        # true = observe-only (log, don't enforce)
max_calls_per_minute: 60
blocked_tools: []
dlp_category_thresholds:
  pii: 0.65
  secret: 0.5
  financial: 0.5

Edit it and the daemon hot-reloads within seconds. A connected agent receives this same object, HMAC-signed, from its control plane.

---

Supported MCP clients

Claude Desktop · Cursor · Claude Code · OpenAI Codex · Windsurf · VS Code (Copilot) · Gemini CLI · Zed · Cline · Roo Code · Continue.dev · Amazon Q — plus a system-wide scan that picks up MCP servers from unknown clients.

Both stdio and Streamable HTTP MCP servers are proxied.

---

Platform support

Platform	Service	Installer
macOS	launchd LaunchAgent	.pkg
Linux	systemd user service	.deb
Windows	Windows Service	.msi

---

Development

git clone https://github.com/joshmaster2165/medusa-agent.git
cd medusa-agent
poetry install
poetry run pytest tests/ -q          # test suite
poetry run ruff check src/ tests/    # lint
poetry run ruff format src/ tests/   # format

src/medusa/
  gateway/      # proxy, policy engine, DLP scanner, write accumulator
  agent/        # daemon, installer, control_plane client, doctor
  cli/          # the medusa-agent CLI
  connectors/   # MCP client auto-discovery
  models/       # tokenizer + label map (ONNX model fetched separately)

See CONTRIBUTING.md to get started, and docs/control-plane-api.md for the agent↔control-plane wire contract.

---

Security

To report a vulnerability, see SECURITY.md. Please do not open a public issue for security problems.

License

Apache 2.0. The agent is free and open source. A commercial fleet dashboard is available separately.